home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
CU Amiga Super CD-ROM 17
/
CU Amiga Magazine's Super CD-ROM 17 (1997)(EMAP Images)(GB)[!][issue 1997-12].iso
/
CUCD
/
Programming
/
DiceSource
/
doc
/
dice_libraries.doc
< prev
next >
Wrap
Text File
|
1994-02-13
|
202KB
|
7,659 lines
dice/AslBase,DiceCacheBase,DiskfontBase,DOSBase,FifoBase,GadToolsBase,IconBase,IntuitionBase,LayersBase,MathBase,MathIeeeDoubBasBase,MathIeeeDoubTransBase,MathIeeeSingBasBase,MathIeeeSingTransBase,MathTransBase,RexxSysBase,SysBase,TimerBase,TranslatorB
se,UtilityBase
FUNCTION
DICE will automatically open libraries for you (DICE)
DESCRIPTION
With DICE you need not worry about opening or closing Amiga
libraries. You don't have to deal with the mess and hassle of
checking error returns from each open. If a function call to a
library is used, the library base variable will be referenced. If
you did not explicitly define the variable, DICE will insert it,
along with code to open and close the library.
For example, if the _IntuitionBase base variable is referenced (say,
with extern) but not declared then _IntuitionBase will be
automatically declared in auto.lib. Additionally, auto.lib adds
routines to the autoinit and autoexit sequences that automatically
open "intuition.library" before _main and close it after _exit. If
the auto-open fails the program will be aborted before _main is ever
called. The autoexit routine that closes the library first checks to
see if the base variable is NULL and skips trying to close the
library if so.
EXAMPLE
/*
** Example program which just calls an
** intuition.library function without
** bothering to open the library.
*/
main()
{
DisplayBeep( 0 );
}
dice/abort dice/abort
FUNCTION
abort a program with an error (ANSI)
SYNTAX
#include <stdlib.h>
void abort(void);
DESCRIPTION
abort aborts a program with a non-zero exit code. The default abort
routine in c.lib does the equivalent of an exit(20);. Programmers may
overide the default abort routine with thier own.
RESULTS
abort never returns
SEE ALSO
assert
EXAMPLE
#include <stdio.h>
#include <stdlib.h>
main(int ac, char**av)
{
if (ac == 1) {
puts("Hey, I expected a parameter!");
abort();
}
puts("Thanks!");
return(0);
}
dice/abs,labs dice/abs,labs
FUNCTION
take absolute value (ANSI)
SYNTAX
#include <stdio.h>
#include <stdlib.h>
int r = [l]abs(n);
int n;
DESCRIPTION
abs takes the absolute value of an int; labs takes the absolute value
of a long. Both return the absolute value of the specified integer.
For example, r = n if n >= 0, r = -n (positive) if n < 0. Normally
one would not use this call due to overhead, but it exists for
compatibility.
## WARNING: The absolute value of 0x80000000 cannot be taken.
## 0x80000000 will be returned.
|| NOTE: UNDER DICE, sizeof(int) == sizeof(long) and these two
|| functions are thus identical.
INPUTS
int n; integer
RESULTS
int r; absolute value of integer
EXAMPLE
#include<stdio.h>
#include <stdlib.h>
main()
{
int n = -53;
printf("The absolute value of %d is %d\n", n, abs(n));
sleep(1);
printf("But its faster if you write a macro:\n");
#define abs(x) (((x) < 0) ? -(x) : (x))
sleep(1);
printf("The absolute value of %d is %d\n", n, abs(n));
return(0);
}
dice/access dice/access
FUNCTION
determine whether file is accessable (UNIX)
SYNTAX
#include <stdio.h>
int r = access(filename, mode);
const char *filename;
int mode;
DESCRIPTION
access returns 0 upon success, -1 if access with the requested modes
was impossible. The filename serves as a pointer to the string of
the filename we wish to check, and the modes are what we expect the
file to be able to do. The modes may be one or more of the following
OR'd together.
0 check for existance of file only
1 check execute permission for file
2 check write permission for file
4 check read permission for file
INPUTS
char *filename; file to check
int mode; modes as specified above
RESULTS
int r; 0 if modes available, -1 if not
SEE ALSO
open, fopen
EXAMPLE
#include <stdio.h>
main(int ac, char **av)
{
char *name;
if (ac == 1)
{
puts("Expected a file name argument");
exit(1);
}
name = av[1];
if (access(name, 0) == 0) {
puts("It exists");
if (access(name, 1) == 0)
puts("It is executable");
if (access(name, 2) == 0)
puts("I can write to it!");
if (access(name, 4) == 0)
puts("I can even read from it!");
}
else
puts("Hmmm, that file does not exist");
}
dice/acos dice/acos
FUNCTION
take arc cosine (ANSI)
LIBRARY
m.lib
SYNTAX
#include <math.h>
double a = acos(b);
double b;
DESCRIPTION
acos returns the arc cosine of a double quantity.
INPUTS
double b; double floating point value
RESULTS
double a; result double floating point value
SEE ALSO
asin, atan, cos, exp, fabs, log, log10, pow, sin, sqrt, tan, facos,
fasin
EXAMPLE
/*
* compile with the math library -lm
*/
#include <math.h>
#include <stdio.h>
main()
{
{
double a = acos(0.25);
printf("acos 0.25 = %lf\n", a); /* 1.318 */
}
{ /* less accuracy */
float a = facos(0.25);
printf("acos 0.25 = %lf\n", (double)a);
}
return(0);
}
dice/alloca dice/alloca
FUNCTION
allocate memory from the stack (UNIX)
SYNTAX
#include <stdlib.h>
void *ptr = alloca(long bytes);
DESCRIPTION
alloca comes from the UNIX world. It allocates memory off the stack
for use within a procedure. The allocated memory is automatically
freed when the subroutine returns.
:: Beginner's Note: Do not use alloca if you can help it; alloca is
:: not easily portable across machines.
|| NOTE: When a low stack condition arises, alloca will abort by
|| printing an error message and calling abort; alloca does not
|| currently try to allocate dynamic memory when it runs out of
|| stack. Some implementations of alloca use alloca(0) to free
|| allocated stack. This feature is not currently implemented in
|| DICE's alloca call.
SEE ALSO
setjmp, longjmp
EXAMPLE
#include <alloca.h>
#include <stdio.h>
main(int ac, char*av[])
{
char *ptr;
if (ac == 1) {
puts("I need test string");
exit(1);
}
ptr = alloca(strlen(av[1]) + 8);
sprintf(ptr, "FOO.%s", av[1]);
puts(ptr);
return(0);
}
dice/asctime dice/asctime
FUNCTION
convert broken down time into standard text (ANSI)
SYNTAX
#include <time.h>
char *str = asctime(ts);
const struct tm *ts;
DESCRIPTION
asctime converts a broken down time in the tm structure to an ASCII
string and returns a pointer to that string. The time string format
is:
on Dec 8 01:53:33 1987\n\0
where \n stands for a newline character and \0 is a terminating NULL.
The string is stored in a static buffer shared by both asctime and
ctime and so will be overwritten whenever either function is called.
INPUTS
struct tm *ts; pointer to a broken down time structure
RESULTS
char *str; pointer to static string
SEE ALSO
time, localtime, asctime, strftime, ctime, clock
EXAMPLE
#include <stdio.h>
#include <time.h>
main()
{
time_t t = time(NULL);
fputs(asctime(localtime(&t)), stdout);
return(0);
}
dice/assert dice/assert
FUNCTION
assert that an expression is true, else abort (ANSI)
SYNTAX
#include <assert.h>
assert(condition); /* MACRO */
DESCRIPTION
assert checks the condition and if not true prints an error message
indicating the source filename and line number that the assertion
failed at, and then aborts. The DICE version of assert generates a
single static string in assert.h for each module containing the file
name. Multiple usages of assert refer to the same physical filename
string.
INPUTS
expression; an expression which the macro negates.
SEE ALSO
abort
EXAMPLE
#include <assert.h>
main(int ac, char **av)
{
assert(ac > 1); /* expect at least one argument! */
return(0);
}
dice/asin dice/asin
FUNCTION
take the arc sine of a double quantity (ANSI)
LIBRARY
m.lib
SYNTAX
#include <math.h>
double a = asin(b);
double b;
DESCRIPTION
asin takes the arc sine of a floating point quantity.
INPUTS
double b; double floating point value
RESULTS
double a; result double floating point value
SEE ALSO
acos, cos, exp, fabs, log, log10, pow, sin, sqrt, tan facos, fasin
EXAMPLE
/*
* compile with the math library -lm
*/
#include <math.h>
#include <stdio.h>
main()
{
{
double a = asin(0.25);
printf("asin 0.25 = %lf\n", a); /* 0.2527 */
}
{ /* less accuracy */
float a = fasin(0.25);
printf("asin 0.25 = %lf\n", (double)a);
}
return(0);
}
dice/atan dice/atan
FUNCTION
take arc tan of a double quantity (ANSI)
LIBRARY
m.lib
SYNTAX
#include <math.h>
double a = atan(b);
double b;
DESCRIPTION
atan takes the arc tangent of a floating point quantity.
INPUTS
double b; double floating point value
RESULTS
double a; result double floating point value
SEE ALSO
acos, asin, cos, exp, fabs, log, log10, pow, sin, sqrt, tan facos,
fasin
EXAMPLE
/*
* compile with the math library -lm
*/
#include <math.h>
#include <stdio.h>
main()
{
{
double a = atan(0.25);
printf("atan 0.25 = %lf\n", a); /* 0.245 */
}
{ /* less accuracy */
float a = fatan(0.25);
printf("atan 0.25 = %lf\n", (double)a);
}
return(0);
}
dice/atexit dice/atexit
FUNCTION
specify routine that is automatically called on exit (ANSI)
SYNTAX
#include <stdio.h>
#include <stdlib.h>
int error = atexit(funcptr);
void (*fptr)(void);
DESCRIPTION
The atexit routine adds a function to the list of functions called
when the program exits. The atexit routine is called before stdio
and file descriptors are closed down. This exit function is called
whenever the program exits, even if main returns normally. atexit
will return 0 on success, -1 on failure. Some systems limit the
number of atexit functions one can add (DICE does not) so if you add
more than one you should check the return value.
INPUTS
void (*fptr)(void);
routine to add to exit call list, takes no
arguments and returns nothing.
RESULTS
int error; 0 on success, -1 on failure.
SEE ALSO
onbreak
EXAMPLE
/*
* Atexit is useful to free up resources that would
* otherwise not be freed up by DICE. For example, any
* thing AllocMem'd. The atexit function is called on
* any exit ... return from main, call to exit, or ^C.
*
* Normally your atexit routine cannot make assumptions
* as to what has been allocated and what has not since
* exit can be called from anywhere in the program.
*/
#include <stdio.h>
#include <stdlib.h>
extern void *AllocMem();
void *MemPtr; long MemLen;
void myexit(void)
{
if (MemPtr) /* only if it is allocated */
FreeMem(MemPtr, MemLen);
MemPtr = NULL;
}
/* Now we can take a ^C anywhere... before we allocate,
* after, or even after we free (note I am careful to set
* MemPtr back to NULL!)
*/
main()
{
short i;
atexit(myexit);
for (i = 0; i < 50; ++i)
printf("Before %d\t(%ld)\n", i, AvailMem(0) );
MemLen = 32;
MemPtr = AllocMem(MemLen, 0);
if (! MemPtr) {
exit(20);
}
for (i = 0; i < 50; ++i)
printf("During %d\t(%ld)\n", i, AvailMem(0) );
FreeMem(MemPtr, MemLen);
MemPtr = NULL; /* Mark as freed */
for (i = 0; i < 50; ++i)
printf("After %d\t(%ld)\n", i, AvailMem(0) );
return(0);
}
dice/atof dice/atof
FUNCTION
convert string into double floating point value (ANSI)
SYNTAX
#include <stdio.h>
#include <stdlib.h>
double d = atof(str);
const char *str;
DESCRIPTION
atof converts a string into a double floating point value; it is
equivalent to calling strtod(str, NULL). Please refer to strtod for
more information.
INPUTS
char *str; string, like "1.234E-4";
RESULTS
double d; double fp representation of string
SEE ALSO
strtod
dice/atoi,atol dice/atoi,atol
FUNCTION
convert string into integer (ANSI)
SYNTAX
#include <stdio.h>
#include <stdlib.h>
int x =atoi(str);
long y = atol(str);
const char *str;
DESCRIPTION
atoi and atol convert a string of decimal integers into an integer.
It skips initial white space, processes an optional negative sign
('-'), processes digits '0' - '9', and returns the integer. atoi and
atol have been superseded by the strtol function which can handle
numbers of any base.
|| NOTE: Under DICE, sizeof(int) == sizeof(long), and thus atoi and
|| atol are exactly the same.
INPUTS
char *str; string to convert to int
RESULTS
int x; integer result long y; integer result
SEE ALSO
strtol
EXAMPLE
#include <stdio.h>
#include <stdlib.h>
main()
{
int i = atoi(" \t\t -123");
printf("i = %d (-123?)\n", i);
return(0);
}
dice/bcmp dice/bcmp
FUNCTION
compare two memory buffers (UNIX)
SYNTAX
#include <string.h>
int r = bcmp(s1, s2, bytes)
void *s1;
void *s2;
size_t bytes;
DESCRIPTION
bcmp compares two memory buffers. A byte by byte (unsigned)
comparison is done. When a comparison fails and the byte in s1 is
less than the byte in s2 then -1 is returned. If the byte in s1 is
greater than the byte in s2 then 1 is returned. If the count is
exhausted and all comparisons succeed then 0 is returned indicating
the two buffers are the same.
INPUTS
void *s1; pointer to first buffer
void *s2; pointer to second buffer
size_t bytes; size of each buffer
RESULTS
int r; -1 if buf s1 < buf s2, 0 if buf s1 == buf s2, 1
if buf s1 > buf s2.
SEE ALSO
cmpmem, memcmp, strcmp
EXAMPLE
#include <stdlib.h>
#include <assert.h>
main()
{
unsigned char buf1[] = {5, 12, 13};
unsigned char buf2[] = {5, 12, 13};
int r;
r = bcmp(buf1, buf2, 3);
assert(r == 0);
buf1[2] = 12;
r = bcmp(buf1, buf2, 3);
assert(r < 0);
buf1[2] = 200;
r = bcmp(buf1, buf2, 3);
assert(r > 0);
return(0);
}
dice/c.o dice/c.o
FUNCTION
DICE startup module for all C programs
SYNTAX
The module dlib:c.o is normally specified first in a link line, or
automatically by dcc.
DESCRIPTION
C programs require a bit of code (called "glue") in order to start
execution. This code saves machine registers, sets up global
storage, parses arguments, open libraries and, after the program
terminates, communicates results back to the host Operating System.
For use with the Amiga, DICE includes a suitable startup module
called c.o. This module is automatically include by dcc, and need
not concern most programmers.
The startup module performs the following tasks:
1) Save non-scratch registers.
2) If resident, allocate space for both DATA (Initialized globals) &
BSS (Uninitialized globals - set to zero). Copy initialized data
into the allocated space. Clear the BSS portion of the data space.
If the BSS has already been allocated by the load module but not
cleared, clear the BSS portion of the data space.
3) Clear the ^C (Control C) signal
4) Setup _SysBase, the pointer to the Amiga's master library, Exec.
5) Call all AUTOINIT subroutines (this usually results in at least
the dos.library being opened).
6) Call _main (usually the c.lib version, but you may override it).
7) Fall through to _exit(0). Note that while c.a falls through to
_exit after calling _main, _main itself calls main with:
exit(main(args...)); Thus, main() is always expected to return a
valid value (i.e. not void).
C.O. also handles the low-level _exit (__exit:) in the following
sequence:
1) Call all AUTOEXEC subroutines (this normally closes the DOS
library and other automatically opened libraries such as floating
point).
2) Free all memory allocated by the task, including the small data
segment & BSS space. Note that all variables we use hereafter
have already been placed in registers since the dataspace is no
longer valid.
3) If started from workbench, reply to the workbench mesage, _WBMsg.
4) Restore original registers and rts (exit back to the Operating
System).
c.o also exists in c.lib, however that version is not normally used.
|| NOTE: Normally the programmer does not overide the startup object
|| file (c.o).
However, in some cases a programmer will want to overide _main, as
in:
_main(len, arg) int len; char *arg; {... }
The _main entry point is passed the length and arg pointer unmodified
from the OS. When you overide _main you cannot call any stdio (fopen,
fclose, puts, printf, etc...), any low level IO (open, close, read,
write, etc...), or any C memory allocation routine (malloc, etc...).
Normally _main will be overridden if the programer wishes to save
space, and makes only Amiga system calls (such as Open, Close, Read,
Write, FindTask, etc.). Overriding the C.LIB generally makes
executables much smaller because no extraneous stdio or low level IO
routines are brought in from c.lib. Normally you exit out of _main by
calling _exit(code) (note the underscore).
dice/calloc dice/calloc
FUNCTION
allocate memory and clear (ANSI)
SYNTAX
#include <stdlib.h>
void *ptr = calloc(objsize, numobjs)
size_t objsize;
size_t numobjs;
DESCRIPTION
Numobjs objects each objsize in size are allocated contiguously and a
pointer to the first object is returned. The memory is cleared to 0.
Effectively this is equivalent to malloc(objsize * numobjs), and then
setmem(ptr, objsize * numobjs, 0) . calloc returns NULL if the memory
cannot be allocated.
INPUTS
size_t objsize; size of each object
size_t numobjs; number of objects to allocate
RESULTS
void *ptr; pointer to first object
SEE ALSO
malloc, strdup
EXAMPLE
/*
* allocate 16 objects and fill with junk
*/
#include <stdlib.h>
#include <assert.h>
typedef struct
{
long a, b, c;
}
Junk;
main()
{
Junk *jp;
jp = calloc(sizeof(Junk), 16);
assert(jp);
{
Junk *tj = jp;
short i;
for (i = 0; i < 16; ++i, ++tj)
{
tj->a = 1;
tj->b = 2;
tj->c = 3;
}
}
free(jp);
return(0);
}
dice/chdir dice/chdir
FUNCTION
change current directory (UNIX)
SYNTAX
#include <stdio.h>
int r = chdir(path);
const char *path;
DESCRIPTION
chdir changes the current directory to the specified path, returning
0 on success and -1 on failure.
|| NOTE: When a program exits, the original directory will be
|| restored.
INPUTS
char *path; path to chdir into
RESULTS
int r; return value, 0 if ok, -1 if error
SEE ALSO
getcwd
EXAMPLE
#include <stdio.h>
char buf[512];
main(int ac, char **av)
{
getcwd(buf, sizeof(buf));
if (chdir("RAM:")) {
puts("Couldn't chdir into RAM:");
exit(1);
}
FILE *fp;
if (fp = fopen("yy", "w")) {
fputs("Fight for vegtable rights!\n", fp);
fclose(fp);
puts("created file yy in RAM:");
}
if (chdir(buf)) {
printf("Unable to chdir back into %s\n", buf);
}
return(0);
}
dice/chkabort dice/chkabort
FUNCTION
Check for ^C and take the appropriate action (AmigaDOS)
SYNTAX
(void) chkabort(void);
DESCRIPTION
chkabort checks for a ^C and takes the appropriate action. If the
appropriate action is to exit then this routine does not return.
Stdio and other routines will call chkabort at various points. The
action taken by ^C may be set by the signal or onbreak calls.
SEE ALSO
onbreak, atexit, signal
EXAMPLE
/*
* wait for somebody to hit ^C (note that this is very
* wasteful of CPU and thus isn't a real good example).
*/
main()
{
int i;
for (i = 0; i < 10000000; ++i)
chkabort();
return(0);
}
dice/clearerr dice/clearerr
FUNCTION
Clear error associated with a file pointer (ANSI)
SYNTAX
#include <stdio.h>
void clearerr(fp);
(MACRO) FILE *fp;
DESCRIPTION
The clearerr macro clears both the EOF flag and the ERROR flag
associated with a file pointer. When an ERROR occurs on a file
pointer, addition fread, fwrite, etc. calls will not work until the
ERROR indicator is cleared.
|| NOTE: Refer to the file_pointer manual page for general
|| information.
INPUTS
FILE *fp; file pointer to clear the error on.
RESULTS
none; the error and EOF indicators are cleared
SEE ALSO
feof, ferror, rewind, fseek
dice/clock dice/clock
FUNCTION
return system clock value (ANSI)
SYNTAX
#include <time.h>
clock_t clk = clock(void);
DESCRIPTION
clock returns the system clock in ticks. To obtain seconds from
ticks divide the returned value by CLK_TCK in <time.h>.
INPUTS
none
RESULTS
clock_t clk; system clock time value
SEE ALSO
time, localtime, asctime, strftime, ctime, clock
EXAMPLE
#include <stdio.h>
#include <time.h>
main()
{
clock_t clk = clock();
long i;
clk = clk + CLK_TCK;
for (i = 0; clk - clock() > 0; ++i)
;
printf("The FOR loop calling clock() took\
%d loops in one second\n", i);
return(0);
}
dice/close dice/close
FUNCTION
close a file descriptor (UNIX)
SYNTAX
#include <fcntl.h>
int r = close(fd);
int fd;
DESCRIPTION
close closes a file descriptor. If an error occurs or the descriptor
is invalid, a non-zero return code will result and errno will be set
to the appropriate error condition.
|| NOTE: Refer to the file_descriptor manual page for general
|| information. Unlike file pointers and file handles, the file
|| descriptor is checked for validity and if illegal, an error will
|| be returned.
INPUTS
int fd; file descriptor to close, the file descriptor
becomes invalid after this call
RESULTS
int r; return value, 0 == ok, non-zero == error
SEE ALSO
creat, fcntl, fdtofh, ioctl, isatty, lseek, mkdir, open, read, rmdir,
unlink, write
See open for an example
dice/cmpmem dice/cmpmem
FUNCTION
compare two memory buffers (UNIX)
SYNTAX
#include <string.h>
int r = cmpmem(s1, s2, bytes)
void *s1;
void *s2;
size_t bytes;
DESCRIPTION
Like bcmp, this function compares two memory buffers. A byte by byte
(unsigned) comparison is done. When a comparison fails and the byte
in s1 is less than the byte in s2 then -1 is returned. If the byte in
s1 is greater than the byte in s2 then 1 is returned. If the count is
exhausted and all comparisons succeed then 0 is returned indicating
the two buffers are the same.
INPUTS
void *s1; pointer to first buffer
void *s2; pointer to second buffer
size_t bytes; size of each buffer
RESULTS
int r; -1 if buf s1 < buf s2, 0 if buf s1 == buf s2, 1
if buf s1 > buf s2.
SEE ALSO
bcmp, memcmp
EXAMPLE
#include <stdlib.h>
#include <assert.h>
main()
{
unsigned char buf1[] = {3, 5, 7, 11, 13};
unsigned char buf2[] = {3, 5, 7, 11, 13};
int r;
r = cmpmem(buf1, buf2, 5);
assert(r == 0);
buf1[2] = 2;
r = cmpmem(buf1, buf2, 5);
assert(r < 0);
buf1[2] = 200;
r = cmpmem(buf1, buf2, 5);
assert(r > 0);
return(0);
}
dice/cos,fcos dice/cos,fcos
FUNCTION
cos: return cosine of a double (ANSI)
fcos: return cosine of a float (ANSI)
LIBRARY
m.lib
SYNTAX
#include <math.h>
double a = cos(b);
double c;
float c = fcos(d);
double d;
DESCRIPTION
cos returns the cosine of a type double quantity. fcos is the same,
except expexts a type float. These functions use radian measure.
INPUTS
double b; double floating point value
RESULTS
double a; result double floating point value
SEE ALSO
acos, asin, atan, exp, fabs, log, log10, pow, sin, sqrt, tan facos,
fasin, fcos
EXAMPLE
/*
* compile with the math library -lm
*/
#include <math.h>
#include <stdio.h>
main()
{
{
double a = cos(0.25);
printf("cos 0.25 = %lf\n", a); /* 0.9689 */
}
{ /* less accuracy */
float a = fcos(0.25);
printf("cos 0.25 = %lf\n", (double)a);
}
return(0);
}
dice/creat dice/creat
FUNCTION
create a file (UNIX)
SYNTAX
#include <fnctl.h>
int fd = creat(file);
char *file;
DESCRIPTION
creat creates a new file and returns a file descriptor for it. This
call is equivalent to open(file,O_CREAT|O_TRUNC|O_RDWR); this is an
obsolete function and should not be used.
dice/ctime dice/ctime
FUNCTION
convert time into standard text (ANSI)
SYNTAX
#include <time.h>
char *str = ctime(&t); time_t t;
DESCRIPTION
ctime converts a time pointer into ASCII text using the following
format:
Sun Dec 8 01:53:33 1987\n\0
where \n stands for a newline character and \0 is terminating nul.
The string is stored in a static buffer shared by both asctime and
ctime and so will be overwritten whenever either function is called.
INPUTS
time_t *t; pointer to a time_t value
RESULTS
char *str; pointer to static string
SEE ALSO
time, localtime, asctime, strftime, ctime, clock
EXAMPLE
#include <stdio.h>
#include <time.h>
main()
{
time_t t = time(NULL);
fputs(ctime(&t), stdout);
return(0);
}
dice/dir dice/dir
FUNCTION
disk directory scanning (UNIX)
SYNTAX
#include <sys/dir.h>
DIR *dirhan = opendir(path);
struct direct *entry = readdir(dirhan);
(void) rewinddir(dirhan);
void
closedir(dirhan);
const char *path;
DIR *dirhan;
DESCRIPTION
These are UNIX compatible directory scanning calls. After opening a
directory with opendir, you may scan it with successive calls to
readdir until NULL is returned, then either rewinddir it for a
rescan, or closedir it when done. The DIR structure is private to
the library. Valid fields within struct direct are d_name (the file
name), and d_namlen (the length of the file name, not usually
needed). You can chdir into the directory and stat each entry to
obtain additional information. Note that while the UNIX directory
scanning routines will not be as efficient as the Amiga directory
scanning routines, the UNIX directory scanning routines are portable.
|| NOTE: Unlike the Amiga directory scanning routines that use Amiga
|| File Locks, these calls will automatically deallocate resources if
|| the program terminates. rewinddir's prototype returns an int.
|| This is for internal use only. You should never use rewinddir's
|| return value yourself.
SEE ALSO
chdir
EXAMPLE
#include <stdio.h>
#include <sys/dir.h>
main(int ac, char*av[])
{
DIR *dir;
if (ac == 1)
{
puts("test dir");
exit(1);
}
if (dir = opendir(av[1]))
{
struct direct *entry;
while (entry = readdir(dir))
{
printf("%s\n", entry->d_name);
}
closedir(dir);
}
return(0);
}
dice/_divs,_divu dice/_divs,_divu
FUNCTION
Signed and unsigned long divide (DICE)
DESCRIPTION
DICE uses these assembly level functions whenever it needs to do long
division; they are not callable from C.
INPUTS
D0 32 bit signed/unsigned integer
D1 32 bit signed/unsigned integer
RESULTS
D0 D0 divided by D1
SEE ALSO
_mods, _modu, _muls, _mulu
dice/exit dice/exit
FUNCTION
Exit from a program 'nicely' (ANSI)
SYNTAX
#include <stdlib.h>
(void) exit(code)
DESCRIPTION
exit exits the program and returns the specified exit code. Normally
you pass 0 to indicate no errors, and a positive number to indicate a
program error to the parent. exit closes all stdio file pointers,
low level file descriptors, perhaps a few other things, and then
finally calls _exit with the code. If you use main you should call
exit to exit the program or return an error code from main. If you
use the _main entry point (only for programmers dead set on
optimizing executable size and using only system library calls) you
should use the _exit exit point.
SEE ALSO
main, _main, _exit
EXAMPLE
main(int ac, char *av[])
{
if (ac <= 1) {
puts("Sorry, you must supply a parameter!");
exit(1);
}
puts("Thanks!");
exit(0);
}
dice/_exit dice/_exit
FUNCTION
exit from a program without bothering to release resources (ANSI)
SYNTAX
#include <stdlib.h>
(void) _exit(code)
int code;
DESCRIPTION
_exit exits from a program and returns the specified exit code.
Normally you pass 0 to indicate no errors, a positive number to
indicate a program error to the parent. Note that since auto-init
opened libraries are closed in the startup module (c.o),
automatically opened libraries will be automatically closed for you.
However, any libraries you manually declare the library base variable
for and manually open must be closed by you. You should only call
_exit if you used the _main entry point (instead of the usual main),
and then only after releasing all resources (such as file handles
opened with open).
INPUTS
code int; code is a value that is passed back to
caller
SEE ALSO
main, _main, exit
EXAMPLE
_main()
{
Write(Output(), "Ouch!!\n", 7);
_exit(20); /* 20 - Severe Error */
}
dice/exp dice/exp
FUNCTION
return e to the power of the double quantity (ANSI)
LIBRARY
m.lib
SYNTAX
#include <math.h>
double a = exp(b);
double b;
DESCRIPTION
exp returns e to the power of the floating point quantity.
INPUTS
double b; double floating point value
RESULTS
double a; result double floating point value
SEE ALSO
acos, asin, atan, cos, fabs, log, log10, pow, sin, sqrt, tan facos,
fasin
EXAMPLE
/*
* compile with the math library -lm
*/
#include <math.h>
#include <stdio.h>
main()
{
{
double a = exp(0.25);
printf("exp 0.25 = %lf\n", a);
}
{ /* less accuracy */
float a = fexp(0.25);
printf("exp 0.25 = %lf\n", (double)a);
}
return(0);
}
dice/expand_args dice/expand_args
FUNCTION
expand command line argument wildcards (DICE)
SYNTAX
#include <stdio.h>
int error = expand_args(xac, xav, &ac, &av);
int xac;
const char **xav;
int ac;
char **av;
DESCRIPTION
expand_args is a powerful and convenient function. A few lines of
simple code allow your program to have full wildcard support under
any version of the OS. expand_args takes an argc/argv list and
expands any wildcard arguments by scanning the appropriate directory.
It malloc's however much memory it needs to create the new list and
ignores xav[0] (that is, it just copies it to the returned av[0]
without doing a wildcard expansion). expand_args fills in the ac and
av variables with its own malloc'd version of the argument list, now
completely expanded. There is no limit to the number of files that
may be in this result list (you could conceivably have thousands).
expand_args may be used to expand arbitrary AmigaDOS wildcards and is
not limited to an anchored search. For example, you could specify:
sys:#?/#? in which case a list of a second level files/dirs will be
generated. In the above case, expand_args scans sys, then scans any
sub directories found in sys. Generic AmigaDOS wildcarding is used
and incredibly complex wildcards may be specified. Please note,
however, that any wildcard elements containing #? in combination with
other elements (such as (a|b|c)) will cause huge amounts of stack to
be used and also quite a bit of memory during the scan. expand_args
limits itself to 4K of stack before giving up. Any program that uses
expand_args should be run with at least 8K of stack.
INPUTS
int xac; original argc
char **xav; original argv
int *ac; pointer to new argc
char ***av; pointer to new argv
RESULTS
int error; 0 if all went well, non-zero otherwise
EXAMPLE
#include <stdio.h>
main(int xac, char **xav)
{
int ac, i, error;
char **av;
int error = expand_args(xac, xav, &ac, &av);
for (i = 1; i < ac; ++i) {
printf("%s\n", av[i]);
}
} /* expand_args #?.c */
dice/fabs dice/fabs
FUNCTION
return the absolute value of a double quantity (ANSI)
LIBRARY
m.lib
SYNTAX
#include <math.h>
double a = fabs(b);
double b;
DESCRIPTION
fabs returns the absolute value of a floating point quantity.
INPUTS
float d; float floating point value
RESULTS
int arg; control argument
int r; result, error if less than 0.
EXAMPLE
/*
* compile with the math library -lm
*/
#include <math.h>
#include <stdio.h>
main()
{
{
double a = fabs(-0.25);
printf("fabs -0.25 = %lf\n", a); /* 0.25 */
}
{ /* less accuracy */
float a = ffabs(-0.25);
printf("fabs -0.25 = %lf\n", (double)a);
}
return(0);
}
dice/facos dice/facos
FUNCTON
float arc cosine (UNIX)
LIBRARY
m.lib
SYNTAX
#include <math.h>
float c = facos(d);
float d;
DESCRIPTION
facos returns the arc cosine of a floating point quantity.
INPUTS
float d; float floating point value
RESULTS
result float; floating point value
SEE ALSO
acos, asin, atan, cos, exp, fabs, log, log10, pow, sin, sqrt, tan,
fasin
EXAMPLE
/*
* compile with the math library -lm
*/
#include <math.h>
#include <stdio.h>
main()
{
{
double a = acos(0.25);
printf("acos 0.25 = %lf\n", a); /* 1.318 */
}
{ /* less accuracy */
float a = facos(0.25);
printf("acos 0.25 = %lf\n", (double)a);
}
return(0);
}
dice/fasin dice/fasin
FUNCTION
return arc sine of a float quantity (UNIX)
LIBRARY
m.lib
SYNTAX
#include <math.h>
float c = fasin(d);
float d;
DESCRIPTION
fasin returns the arc sine of a floating point quantity.
INPUTS
float d; float floating point value
RESULTS
float c; result float loating point value
SEE ALSO
acos, asin, atan, cos, exp, fabs, log, log10, pow, sin, sqrt, tan
facos
EXAMPLE
/*
* compile with the math library -lm
*/
#include <math.h>
#include <stdio.h>
main()
{
{
double a = asin(0.25);
printf("asin 0.25 = %lf\n", a); /* 0.2527 */
}
{ /* less accuracy */
float a = fasin(0.25);
printf("asin 0.25 = %lf\n", (double)a);
}
return(0);
}
dice/fatan dice/fatan
FUNCTION
return arc tan of a float quantity (UNIX)
LIBRARY
m.lib
SYNTAX
#include <math.h>
float c = fatan(d); float d;
DESCRIPTION
fatan returns the arc tan of a floating point quantity.
INPUTS
float d; float floating point value
RESULTS
float c; result float floating point value
SEE ALSO
acos, asin, atan, cos, exp, fabs, log, log10, pow, sin, sqrt, tan
facos, fasin
EXAMPLE
/*
* compile with the math library -lm
*/
#include <math.h>
#include <stdio.h>
main()
{
{
double a = atan(0.25);
printf("atan 0.25 = %lf\n", a); /* 0.245 */
}
{ /* less accuracy */
float a = fatan(0.25);
printf("atan 0.25 = %lf\n", (double)a);
}
return(0);
}
dice/fclose dice/fclose
FUNCTION
close a file pointer (ANSI)
SYNTAX
#include <stdio.h>
int error = fclose(fp);
FILE *fp;
DESCRIPTION
fclose flushes any data remaining in the file pointer's output buffer
to the file and then closes the file. The file pointer is no longer
valid. fclose returns any error condition that occured while it was
flushing the buffered data to the file. The file is closed even if
an error occured.
|| NOTE: You can fclose(stdin), fclose(stdout), and fclose(stderr) to
|| save space or detach your process from the console (i.e. allow the
|| console window to be closed).
## WARNING: If you fclose stdin, stdout, and stderr with the
## intention of removing all references to the console window, you
## must put a NULL in your processes pr_ConsoleTask field. Otherwise,
## the console window will be able to close, but your process will
## still have a reference to the now non-existent window. Refer to
## the file_pointer manual page for general information
INPUTS
FILE *F; file pointer
RESULTS
int error; error on fclose, or 0 if none
SEE ALSO
fopen, fread, fwrite, fgets, fputs
dice/fcntl dice/fcntl
FUNCTION
file control on a file (UNIX)
SYNTAX
#include <fcntl.h>
int r = fcntl(fd, req, arg)
int fd;
int req;
int arg;
DESCRIPTION
fcntl may be used to control various aspects of an fd and is a higher
level call than ioctl. Currently, nothing truly significant can be
accomplished by a fcntl call for files. However, fcntl fully
supports programmer simulated file descriptors.
|| NOTE: Refer to the file_descriptor manual page for general
|| information Unlike file pointers and file handles, the file
|| descriptor is checked for validity and if illegal, an error will
|| be returned.
INPUTS
int fd; file descriptor to operate on
int req; request from <fcntl.h> (F_* defines)
int arg; control argument
RESULTS
int r; result, error if less than 0
SEE ALSO
close, creat, fcntl, fdtofh, ioctl, isatty, lseek, mkdir, open, read,
rmdir, unlink, write
dice/fdopen dice/fdopen
FUNCTION
associate a file pointer with an open file descriptor (UNIX)
SYNTAX
#include <stdio.h>
FILE *fp = fdopen(fd, modes);
int fd; char *modes;
DESCRIPTION
fdopen associates an open file descriptor with a file pointer.
|| NOTE: Once fclose is used, the file pointer will also close the
|| file descriptor. Refer to the fopen manual page for a description
|| of available modes. Also, when you use fdopen the file will not be
|| truncated and if you specify mode a for append, the file
|| descriptor must have been opened with the O_APPEND flag. That is,
|| the mode string should be similar to the open flags that were used
|| to open the file descriptor. Refer to the file_pointer manual page
|| for general information
INPUTS
int fd; file descriptor to associated with a new file
pointer
char *modes; modes string, such as "r+".
RESULTS
FILE *fp; new file pointer or NULL if an error occured
SEE ALSO
fopen, fread, fwrite, fgets, fputs
dice/fdtofh dice/fdtofh
FUNCTION
return AmigaDOS file handle for file descriptor (AmigaDOS)
SYNTAX
#include <stdio.h>
BPTR fh = fdtofh(fd);
int fd;
DESCRIPTION
fdtofh returns the AmigaDOS file handle associated with a file
descriptor or NULL if the file descriptor is illegal or simulated.
You may then make AmigaDOS library calls using the file handle.
INPUTS
int fd; file descriptor
RESULTS
BPTR fh; associated file handle or NULL
SEE ALSO
close, creat, fcntl, ioctl, isatty, lseek, mkdir, open, read, rmdir,
unlink, write
EXAMPLE
#include <stdio.h>
main()
{
FILE * fh;
write(1, "Quayle\n", 6);
if( fh = fdtofh(1) ) /* Example Only! */
Write(fh, "Bait\n", 6);
return(0);
}
dice/feof dice/feof
FUNCTION
test a file pointer for End Of File (ANSI)
SYNTAX
#include <stdio.h>
int r = feof(fp);
(MACRO) FILE *fp;
DESCRIPTION
feof returns the EOF status of a file pointer. The status is not
changed by this macro. 0 is returned if no EOF condition exists,
non-zero if an EOF condition exists (not necessarily 1 or -1, just
non-zero). Use clearerr to clear the EOF condition. Note than fseek
and rewind also clear an EOF condition.
INPUTS
FILE *fp; file pointer
RESULTS
int r; 0 if no EOF condition exists, != 0 if an EOF
condition exists (not necessarily 1 or -1).
SEE ALSO
fopen, fclose, fread, fwrite, fgets, fputs, file_pointer
dice/ferror dice/ferror
FUNCTION
return ERROR condition for file pointer (ANSI)
SYNTAX
#include <stdio.h>
int r = ferror(fp); /* MACRO */
FILE *fp;
DESCRIPTION
ferror returns the ERROR status of a file pointer. The status is not
changed by this macro. 0 is returned if no ERROR condition exists,
non-zero if an ERROR condition exists (not necessarily 1 or -1, just
non-zero).
INPUTS
FILE *fp; file pointer
RESULTS
int r; 0 if no ERROR condition exists, != 0 if an ERROR
condition exists (not necessarily 1 or -1).
SEE ALSO
fopen, fclose, fread, fwrite, fgets, fputs, file_pointer
dice/fexp dice/fexp
FUNCTION
return e to the power of the float quantity (UNIX)
LIBRARY
m.lib
SYNTAX
#include <math.h>
float c = fexp(d);
float d;
DESCRIPTION
fexp returns e to the power of the floating point quantity
INPUTS
float d; float floating point value
RESULTS
float c; result float floating point value
SEE ALSO
acos, asin, atan, cos, exp, fabs, log, log10, pow, sin, sqrt, tan,
facos, fasin
EXAMPLE
/*
* compile with the math library -lm
*/
#include <math.h>
#include <stdio.h>
main()
{
{
double a = exp(0.25);
printf("exp 0.25 = %lf\n", a);
printf("exp 0 = %lf\n", (double)exp(0) );
}
{ /* less accuracy */
float a = fexp(0.25);
printf("exp 0.25 = %lf\n", (double)a);
}
return(0);
}
dice/ffabs dice/ffabs
FUNCTION
return the absolute value of a float (UNIX)
LIBRARY
m.lib
SYNTAX
#include <math.h>
float c = ffabs(d);
float d;
DESCRIPTION
ffabs returns the absolute value of a floating point quantity.
INPUTS
float d; float floating point value
RESULTS
int arg; control argument
int r; result, error if less than 0.
SEE ALSO
acos, asin, atan, cos, exp, fabs, log, log10, pow, sin, sqrt, tan,
facos, fasin
EXAMPLE
/*
* compile with the math library -lm
*/
#include <math.h>
#include <stdio.h>
main()
{
{
double a = fabs(-0.25);
printf("fabs -0.25 = %lf\n", a); /* 0.25 */
}
{ /* less accuracy */
float a = ffabs(-0.25);
printf("fabs -0.25 = %lf\n", (double)a);
}
return(0);
}
dice/fflush dice/fflush
FUNCTION
flush buffers to file (ANSI)
SYNTAX
#include <stdio.h>
int error = fflush(fp);
FILE *fp;
DESCRIPTION
fflush writes out any buffered data out to the file descriptor
associated with the file pointer. Normally a file is either
unbuffered, line buffered, or fully buffered; fflush is useful in
the latter two cases as is shown by the example. The function will
return -1 if a write error occured, 0 if no error occured.
|| NOTE: Refer to the file_pointer manual page for general
|| information.
INPUTS
FILE *fp; file pointer
RESULTS
int error; 0 if no error, -1 on error.
SEE ALSO
fopen, fclose, fread, fwrite, fgets, fputs
EXAMPLE
/*
* Since text to stdout is normally line buffered,
* if we do not write out a newline '\n' then the
* line is still buffered in memory and we have to
* fflush() to write it out.
*/
#include <stdio.h>
main()
{
char buf[256];
printf("Enter a number -");
fflush(stdout);
fgets(buf, sizeof(buf), stdin);
printf("Munch Munch...");
fflush(stdout);
sleep(1);
puts("Thanks!");
}
dice/fgetc,getc dice/fgetc,getc
FUNCTION
fgetc: get a single character (ANSI)
getc: get a single character from a file pointer (ANSI)
SYNTAX
#include <stdio.h>
int c = fgetc(fp);
int c = getc(fp); /* MACRO */
FILE *fp;
DESCRIPTION
getc and fgetc both read a single character from a file pointer. The
value returned is actually an int because EOF (-1) must be
differentiated from a 255. Each returns an integer 0-255 or EOF (-1)
if an end of file occurs.
|| NOTE: Refer to the file_pointer manual page for general
|| information.
INPUTS
FILE *fp; file pointer
RESULTS
int c; character 0 to 255, or EOF (-1).
SEE ALSO
putc, fputc, fread, fwrite
EXAMPLE
/*
* copy stdin to stdout using getc/putc. Normally
* one uses fread/fwrite, but I'll save that for the
* fread manual page.
* Note that I output the initial message to stderr so
* it does not get stuck into stdout in case the user
* has redirected stdout.
*/
#include <stdio.h>
main()
{
int c;
fputs("Type a couple of lines, then ^\\ (EOF)\n",
stderr);
while ((c = getc(stdin)) != EOF)
{
putc(c, stdout);
}
return(0);
}
dice/fgetpos dice/fgetpos
FUNCTION
get current file position (ANSI)
SYNTAX
#include <stdio.h>
int error = fgetpos(fp, &pos);
fpos_t pos;
DESCRIPTION
fgetpos returns the current seek position and is roughly equivalent
to ftell. fgetpos is a new ANSI call to better support C compilers
that use 16 bit integers. DICE uses 32 bit integers so fgetpos is
not so useful. fgetpos takes a file pointer and the address of a
fpos_t type (a long). It fills the fpos_t variable with the current
file position and returns 0 if all went well, non-zero if an error
occured.
|| NOTE: Refer to the file_pointer manual page for general
|| information.
INPUTS
FILE *fp; file pointer
fpos_t *pos; pointer to an fpos_t type that the position is
loaded into.
RESULTS
int error; 0 if no error, non-zero on error
SEE ALSO
ftell, rewind, fseek, rewind
EXAMPLE
/*
** Return the length of the file specified on the
** command line. */
#include <stdio.h>
main(int ac, char*av[])
{
FILE *fp;
fpos_t off;
if (ac == 1) {
puts("Expected a filename argument");
exit(1);
}
fp = fopen(av[1], "r");
if (fp == NULL) {
printf("Unable to open %s\n", av[1]);
exit(5);
}
fseek(fp, 0L, SEEK_END);
if (fgetpos(fp, &off)) {
puts("Error getting file position");
exit(20);
}
fclose(fp);
printf("File %s is %d bytes long\n", av[1], off);
return(0);
}
dice/fgets dice/fgets
FUNCTION
get a line from a file pointer (ANSI)
SYNTAX
#include <stdio.h>
char *ptr = fgets(buf, maxlen, fp);
char *buf;
int maxlen;
FILE *fp;
DESCRIPTION
fgets gets a line from the specified file pointer, returning the
first argument (buf) or NULL if an error or EOF occurs. fgets stores
the line in buf, up to maxlen characters. This maximum includes a
terminating newline '\n' and NULL '\0'. If more than maxlen-1
characters are in the line fgets will terminate operation and put a
NULL as the last character (so the buffer will still be a valid
string). It is common to become confused by these functions:
gets, puts
These functions strip newline on input, add newline on output.
gets works on stdin, puts on stdout.
fgets, fputs
These functions leave newlines alone on input, don't add to the
output. Any file pointer, including stdin and stdout may be
specified.
|| NOTE: Refer to the file_pointer manual page for general
|| information.
INPUTS
char *buf; buffer
int maxlen; maximum buffer size
FILE *fp; file pointer
RESULTS
char *ptr; buf if all is well, or NULL if error or EOF
SEE ALSO
gets, puts, fputs, fread, getc, fgetc
EXAMPLE
#include <stdio.h>
main()
{
unsigned char buf[128];
short i;
printf("Enter a line - ");
fflush(stdout);
if (fgets(buf, sizeof(buf), stdin) == NULL)
exit(1);
printf("In Hex: ");
for (i = 0; buf[i]; ++i) printf(" %02x", buf[i]);
puts("");
return(0);
}
dice/fhprintf dice/fhprintf
FUNCTION
formatted printing to a DOS file handle (AmigaDOS)
SYNTAX
#include <stdio.h>
int n = fhprintf(fh, ctl, ...);
BPTR fh;
const char *ctl;
DESCRIPTION
fhprintf provides a method of using DICE's pfmt lib to do formatted
printing to a file handle instead of a stdio file pointer. Output is
unbuffered and thus not very efficient, but the call can be extremely
useful when debugging libraries and such. If you have just a few
things to print, and want to save the space the entire stdio package
takes, you could use this function and _main.
INPUTS
BPTR fh; DOS file handle
const char *ctl; format string, see printf()
RESULTS
int n; number of characters output
SEE ALSO
printf, sprintf, vsprintf, fprintf, vfprintf, _main
EXAMPLE
void _main(int ac, char**av)
{
fhprintf(Output(), "The answer is %d!\n", 42);
}
dice/file_descriptor dice/file_descriptor
FUNCTION
file descriptor
DESCRIPTION
A file descriptor is the lowest portable access to the file system a
C program may make. File descriptors are used with open, read,
write, close, etc. A file descriptor is unbuffered (that is, every
operation goes to the kernel and does not get buffered locally).
|| NOTE: Remember that a file descriptor is different from a stdio
|| file pointer (see the file_pointer manual page) and an AmigaDOS
|| file handle.
dice/fileno dice/fileno
FUNCTION
return file descriptor given a file pointer (UNIX)
SYNTAX
#include <stdio.h>
int fd = fileno(fp); /* MACRO */
FILE *fp;
DESCRIPTION
The fileno macro returns the file descriptor (open, close, read,
write) associated with the file pointer (fopen, fclose, fread,
fwrite). This is still not the AmigaDOS file handle; to get that you
must use the fdtofh call.
## WARNING: If you use the file descriptor of a file pointer the file
## pointer will get its seek position confused. Additionally, there
## might be unflushed data in the file pointer's buffers that has not
## been written out to the file descriptor yet. There also might be
## unread input on the file pointer's input buffers already read from
## the file descriptor.
|| NOTE: Refer to the file_pointer manual page for general
|| information.
INPUTS
FILE *fp; file pointer
RESULTS
int fd; associated file descriptor
SEE ALSO
fdopen, fopen, fclose, open, close
dice/file_pointer dice/file_pointer
FUNCTION
STDIO file_pointer (ANSI)
DESCRIPTION
A file pointer is the basis for stdio, a standard file management
package available across all versions of C. If you stick to the
standard functions, your program should work on any machine that can
compile C.
The specific Amiga implementation builds file pointers (type "FILE
*") on top of file descriptors (type "int"; see the file_descriptor
manual page). File pointers have a layer of buffering (good if you
use many small reads and writes), while file descriptors pass
requests directly to AmigaDOS. Note that a stdio file pointer is not
a file descriptor nor is a AmigaDOS file handle. You may call only
stdio routines (fopen, fclose, fread, fwrite, etc.) with file
pointers.
Some C implementations flush stdout whenever stdin is read. DICE
does not do this.
dice/fopen dice/fopen
FUNCTION
open a file and create a file pointer (ANSI)
SYNTAX
#include <stdio.h>
FILE *fp = fopen(filename, modes)
char *filename;
char *modes;
DESCRIPTION
fopen is the grand master of stdio: it opens and possibly creates a
file and returns a new file pointer for use by the program. The first
argument is the file to open, the second is a string containing one
or mode characters defined as follows:
Mode : Usage
=====+======================================================================
r : open for reading, the file must already exist
-----+----------------------------------------------------------------------
w : open for writing, the file is created if it does not exist,
: truncated if it does
-----+----------------------------------------------------------------------
a : open for append, writes always append to the file.
-----+----------------------------------------------------------------------
a : the file starts out positioned at the end instead of at the
: beginning. This mode also creates the file but only if it does not
: already exist.
-----+----------------------------------------------------------------------
r+ : also allows writing to the file in addition to reading
-----+----------------------------------------------------------------------
w+ : also allows reading from the file
-----+----------------------------------------------------------------------
b : open for binary read/write, else the file is assumed to contain
: text (this is ignored by DICE since there is no difference on the
: Amiga).
-----+----------------------------------------------------------------------
All combinations except "rw" are allowed. One uses "r+" or "w+"
instead of "rw". By the above description "r+" is used to update an
existing file while "w+" is used to create a new file and then allow
reads as well as writes to it. "wa" is equivalent to creating a new
file and then appending to it. "r+a" is equivalent to appending to an
already existing file. Other examples of valid modes combinations:
"r+b", "w+b", "rb", "wb", "ab", "w", "r", "r+", "a", etc...
|| NOTE: Refer to the file_pointer manual page for general
|| information.
INPUTS
char *filename; file name to open
char *modes; open modes string
RESULTS
FILE *fp; new file pointer
SEE ALSO
fdopen, fclose, open, close
EXAMPLE
#include <stdio.h>
main()
{
FILE *fp;
char * filename = "t:XX";
char * why = "I don't do windows\n";
fp = fopen(filename, "wb");
if( fp ) {
fwrite(why, 1, strlen(why), fp);
fwrite(why, strlen(why), 1, fp);
fclose( fp );
} else {
printf("Can't open file %s\n", filename);
}
return(0);
}
dice/fputc,putc dice/fputc,putc
FUNCTION
fputc: write a single character (ANSI)
putc: write a single character (ANSI)
SYNTAX
#include <stdio.h>
int c = fputc(c, fp);
int c = putc(c, fp); /* MACRO */
FILE *fp;
DESCRIPTION
fputc writes a single character to a file pointer. If all goes well
the character is returned, else EOF is returned. fputc is a function
call while putc is a macro
|| NOTE: Refer to the file_pointer manual page for general
|| information.
INPUTS
int c; character to write
FILE *fp; file pointer
RESULTS
int c; character written (same as first argument) or EOF
if error.
SEE ALSO
getc, putc, fputc, fread, fwrite, puts, fputs, gets, fgets
EXAMPLE
/*
* copy stdin to stdout using fgetc/fputc. Normally one
* uses fread/fwrite, but I'll save that for the fread
* manual page. note that I output the initial message
* to stderr so it does not get stuck into stdout in
* case the user has redirected stdout.
*/
#include <stdio.h>
main()
{
int c;
fputs("Type a couple of lines, then ^\\ (EOF)\n",
stderr);
while ((c = fgetc(stdin)) != EOF)
{
fputc(c, stdout);
}
return(0);
}
dice/fputs,puts dice/fputs,puts
FUNCTION
fputs: write a string to a file pointer (ANSI)
puts: then write a string to stdout, appending newline (ANSI)
SYNTAX
#include <stdio.h>
int error = fputs(s, fp);
int error = puts(s);
const char *s;
FILE *fp;
DESCRIPTION
fputs writes a string to a file pointer all the way up to, but not
including, the NULL. puts does the same thing but to stdout, and
puts additionally writes a newline out.
|| NOTE: Refer to the file_pointer manual page for general
|| information.
It is common to get confused between fputs and puts. Remember that
puts adds a newline to the output while fputs does not. gets strips
the newline from an input line while fgets does not.
INPUTS
char *s; string to write
FILE *fp; file pointer
RESULTS
int error; 0 or positive if all went ok, else negative. Note
that unlike printf() routines the numberr of
chars written out is NOT returned.
SEE ALSO
getc, putc, fputc, fread, fwrite, gets, fgets
EXAMPLE
#include <stdio.h>
main()
{
/* note newline */
fputs("This is a test of fputs\n", stdout);
puts("This is a test of puts"); /* note lack of */
puts("That's it!");
return(0);
}
dice/fseek dice/fseek
FUNCTION
seek within a file pointer (ANSI)
SYNTAX
#include <stdio.h>
int error = fseek(fp, offset, how);
FILE *fp;
long offset;
int how;
DESCRIPTION
fseek changes the current seek position within a file. Offset is
interpreted according to the how argument:
: :
=========+===+=======================================================
SEEK_SET : 0 : skip to position relative to beginning of file
---------+---+-------------------------------------------------------
SEEK_CUR : 1 : skip to position relative to current position in file
---------+---+-------------------------------------------------------
SEEK_END : 2 : skip to position relative to end of file.
---------+---+-------------------------------------------------------
So, for example, one may seek to the beginning of a file by fseek(fp,
0L, SEEK_SET);, to the end of the file by fseek(fp, 0L, SEEK_END);.
Calling getc at this time would return an immediate EOF. You can
skip characters in a file with something like fseek(fp, 5L,
SEEK_CUR); which skips 5 characters. Note that when seeking relative
to the end of the file, negative offsets are used. For example, to
seek to the very last character in the file you would use fseek(fp,
-1L, SEEK_END); fseek returns 0 on success, a negative number on
ERROR. A common mistake is to expect fseek to return the new
position of the file but this is not what is returned. Use ftell or
fgetpos to determine the current offset into a file.
|| NOTE: Refer to the file_pointer manual page for general
|| information fseek flushes any buffered write data before seeking.
INPUTS
FILE *fp; file pointer to seek
long offset; relative offset, depending on how
int how; 0, 1, or 2 (absolute, relative, end- relative)
RESULTS
int error; Error code from operation
SEE ALSO
ftell, fgetpos, fsetpos, rewind
EXAMPLE
see fopen for an example
dice/fread dice/fread
FUNCTION
read data from a file pointer (ANSI)
SYNTAX
#include <stdio.h>
size_t robjs = fread(buf, objsize, nobjs, fp);
void *buf; size_t objsize; size_t nobjs;
FILE *fp;
DESCRIPTION
fread reads an arbitrary number of objects from a file pointer into
the specified buffer and returns the actual number of objects read.
If the return value robjs is not equal to nobjs then fread was unable
to read the requested number of objects due to either a read error or
an EOF condition. If the file is already completely exhausted fread
simply returns 0. Having two size arguments, an object size and a
number of objects, simplifies the reading of structure arrays off
disk.
|| NOTE: To use fread to read an arbitrary number of bytes one
|| normally uses the form: r = fread(buf, 1, n, fp); that is, n
|| objects of size 1. fread will attempt to read objsize * nobjs
|| bytes into the specified buffer.
INPUTS
void *buf; buffer to load data into
size_t objsize; size of one object
size_t nobjs; number of objects to read
FILE *fp; file pointer to read objects from
RESULTS
size_t robjs; number of objects actually read or 0 if EOF or
ERROR.
SEE ALSO
fwrite, fopen, fclose, fseek, ftell, rewind
dice/free dice/free
FUNCTION
free memory allocated by calloc, malloc, or strdup (ANSI)
SYNTAX
#include <stdlib.h>
void free(ptr);
void *ptr;
DESCRIPTION
free frees memory allocated by calloc, malloc, or strdup.
|| NOTE: It is illegal to free(NULL). If free is given an illegal
|| pointer or NULL, it will freeze the process by calling wait(0L).
INPUTS
void *ptr; pointer to memory to free
SEE ALSO
malloc, calloc, strdup
EXAMPLE
see calloc example
dice/freopen dice/freopen
FUNCTION
reopen a new file using an existing file pointer, the existing file
is closed before it is reused (ANSI)
SYNTAX
#include <stdio.h>
FILE *fp = freopen(filename, modes, ofp)
char *filename;
char *modes;
FILE *ofp;
DESCRIPTION
freopen works exactly like fopen but takes an additional argument, a
file pointer to reuse. This file pointer, ofp, must reference a valid
open file. freopen will close out ofp then reuse the descriptor to
open the new file, returning ofp (fp == ofp) on success, NULL on
failure. If the freopen fails NULL is returned and the original file
pointer is still closed, but not freed so you may call freopen again
with the same ofp, even though it has already been closed. Refer to
the fopen manual page for information on the modes string. freopen is
often used to change a program's stdin, stdout, or stderr though to
be frank, using a separate file pointer is normally much more
modular.
## WARNING: ANSI does not specify that the ofp can be used in a
## second freopen if the first freopen using ofp fails (returns
## NULL). Many implementations free the file pointer. This just might
## be the proper way of doing things but we don't know. We suggest
## you do not use DICE's feature in that respect as we might have to
## change it back to free ofp if the new file is unopenable.
|| NOTE: Refer to the file_pointer manual page for general
|| information
INPUTS
char *filename; file name to open
char*modes; open modes string
FILE *ofp; open file pointer to reuse
RESULTS
FILE *fp; same as ofp if the new open worked, NULL
otherwise
SEE ALSO
fdopen, fopen, fclose, open, close
EXAMPLE
/*
* re-open stdin to an Amiga console device
*/
#include <stdio.h>
#include <assert.h>
main()
{
char buf[256];
assert(freopen("CON:0/0/320/100/freopen-in", "r",
stdin));
assert(freopen("CON:320/0/320/100/freopen-out", "w",
stdout));
/*
* set to line buffered
*/
setvbuf(stdin, NULL, _IOLBF, 0);
setvbuf(stdout, NULL, _IOLBF, 0);
puts("Type a (short) line in the second window");
gets(buf);
fclose(stdin);
fclose(stdout);
fprintf(stderr, "Your line was: %s\n", buf);
return(0);
}
dice/fsetpos dice/fsetpos
FUNCTION
set position within file pointer (nearly equivalent to fseek
absolute) (ANSI)
SYNTAX
#include <stdio.h>
int error = fsetpos(fp, &pos);
FILE *fp; fpos_t pos;
DESCRIPTION
fsetpos is a nearly useless call that is essentially the same as
fseek(fp, (long)pos, 0); fsetpos seeks within a file pointer to the
absolute position specified by an fpos_t type. The address of an
fpos_t object is passed to fsetpos. Normally one saves the current
seek position into an fpos_t type using the fgetpos function, then
seeks back using the fsetpos function. In this way the programmer
need not make any direct reference to the contents of the fpos_t
type.
INPUTS
FILE *fp; file pointer to seek
fpos_t *pos; pointer to fpos_t type previously initialized by
a fgetpos() call.
RESULTS
int error; 0 if no error, < 0 if error
SEE ALSO
ftell, fsetpos, fseek, rewind
EXAMPLE
/*
* get a line, save current position, get rest of
* file, go back to saved position, retrieve line
* again and print again.
*/
#include <stdio.h>
main(int ac, char*av[])
{
FILE *fp;
fpos_t save_pos;
int count;
char buf[256];
if (ac == 1)
{
puts("Expected textfile argument");
exit(1);
}
fp = fopen(av[1], "r");
if (fp == NULL)
{
printf("Unable to open %s\n", av[1]);
exit(1);
}
for (count = 0; fgets(buf, sizeof(buf), fp);
++count)
{
if (count == 0) /* just before second line */
fgetpos(fp, &save_pos);
fprintf(stdout, "%-3d: %s", count + 1, buf);
}
if (count < 2)
{
puts("not enough lines in file for example!");
exit(1);
}
puts("--end of file, now seeking back to line 2--");
fsetpos(fp, &save_pos);
if (fgets(buf, sizeof(buf), fp) == NULL)
{
puts("error!");
exit(1);
}
fprintf(stdout, "%-3d: %s", 2, buf);
fclose(fp);
return(0);
}
dice/fstat dice/fstat
FUNCTION
stat a file descriptor (UNIX)
SYNTAX
#include <sys/stat.h>
int error = fstat(fd, &stat_buf);
struct stat stat_buf;
DESCRIPTION
fstat is a UNIX-compatible call that returns information pertaining
to the file represented by an open file descriptor. See stat for
information on the struct stat fields.
|| NOTE: fstat works just like stat except you provide a UNIX file
|| descriptor (not an AmigaDOS File Handle).
|| Under 2.0, ExamineFH is used. Under 1.3, the original path used
|| to open the file will be stat'd, which ends up scanning the
|| directory if the file was open for exclusive access.
INPUTS
int fd; file descriptor to stat
struct stat *sbuf;
address of stat structure that will be filled in
RESULTS
int error; 0 on success, < 0 on error
SEE ALSO
chdir
EXAMPLE
#include <stdio.h>
#include <fcntl.h>
#include <sys/stat.h>
main(int ac, char**av)
{
int r, fd;
struct stat stat_buf;
if (ac == 1) {
puts("Expected a file name");
exit(1);
}
fd = open(av[1], O_RDONLY );
if( fd ) {
r = fstat(fd, &stat_buf);
if (r < 0)
printf("Can't stat fd=%d\n", fd);
else {
printf("File is %d bytes\n", stat_buf.st_size);
printf("modified %s", ctime(&stat_buf.st_ctime));
}
close(fd);
}
return(0);
}
dice/ftell dice/ftell
FUNCTION
return current position within file pointer (ANSI)
SYNTAX
#include <stdio.h>
long pos = ftell(fp);
FILE *fp;
DESCRIPTION
ftell returns the current absolute seek offset within a file pointer.
INPUTS
FILE *fp; file pointer retrieve seek position from
RESULTS
long pos; current absolute seek position in file
SEE ALSO
ftell, fgetpos, fsetpos, fseek, rewind
EXAMPLE
/*
* get a line, save current position, get rest of file,
* go backto saved position, retrieve line again and
* print again.
* like fsetpos() example but uses ftell()/fseek()
* instead
*/
#include <stdio.h>
main(int ac, char**av)
{
FILE *fp;
long save_pos;
int count;
char buf[256];
if (ac == 1)
{
puts("Expected textfile argument");
exit(1);
}
fp = fopen(av[1], "r");
if (fp == NULL)
{
printf("Unable to open %s\n", av[1]);
exit(1);
}
for (count = 0; fgets(buf, sizeof(buf), fp); ++count)
{
if (count == 0) /* just before second line */
save_pos = ftell(fp);
fprintf(stdout, "%-3d: %s", count + 1, buf);
}
if (count < 2)
{
puts("not enough lines in file for example!");
exit(1);
}
puts("--end of file, now seeking back to line 2--");
fseek(fp, save_pos, SEEK_SET);
if (fgets(buf, sizeof(buf), fp) == NULL)
{
puts("error!");
exit(1);
}
fprintf(stdout, "%-3d: %s", 2, buf);
fclose(fp);
return(0);
}
dice/fwrite dice/fwrite
FUNCTION
write data to a file pointer (ANSI)
SYNTAX
#include <stdio.h>
size_t robjs = fwrite(buf, objsize, nobjs, fp);
const void *buf;
size_t objsize;
size_t nobjs;
FILE *fp;
DESCRIPTION
fwrite writes the specified number of objects to a file pointer from
the specified buffer and returns the actual number of objects written
or 0 or -1 depending on the error. If the return value robjs is not
equal to nobjs then a write error occured. Having two size arguments,
an object size and number of objects, simplifies the reading of
structure arrays off disk.
|| NOTE: To use fwrite to read an arbitrary number of bytes one
|| normally uses the form "r = fwrite(buf, 1, n, fp);", that is, n
|| objects of size 1.
INPUTS
void *buf; buffer to copy data from
size_t objsize; size of one object
size_t nobjs; number of objects to write
FILE *fp; file pointer to read objects from
RESULTS
size_t robjs; number of objects actually written (0 or EOF on
error)
SEE ALSO
fread, fopen, fclose, fseek, ftell, rewind
dice/getchar dice/getchar
FUNCTION
get character from stdin (ANSI)
SYNTAX
#include <stdio.h>
int c = getchar(); /* MACRO */
DESCRIPTION
getchar returns the next available character on stdin or EOF if no
more characters are available. getchar is equivalent to getc(stdin).
|| NOTE: Refer to the file_pointer manual page for general
|| information.
INPUTS
none
RESULTS
int c; character 0 to 255, or EOF (-1) returned from
stdin
SEE ALSO
putc, putchar, fputc, fread, fwrite, getc
EXAMPLE
/*
* copy stdin to stdout using getchar/putchar. Normally
* one uses fread/fwrite, but I'll save that for the
* fread manual page.
* Note that I output the initial message to stderr
* so it does not get stuck into stdout in case the
* user has redirected stdout.
*
* See getc manual page for equivalent example using
* getc/putc
*/
#include <stdio.h>
main()
{
int c;
fputs("Type a couple of lines, then ^\\ (EOF)\n",
stderr);
while ((c = getchar()) != EOF)
{
putchar(c);
}
return(0);
}
dice/getcwd dice/getcwd
FUNCTION
get current working directory (UNIX)
SYNTAX
#include <stdio.h>
char *path = getcwd(buf, max);
non-standard call
DESCRIPTION
getcwd gets the current working directory and puts it into the
specified buffer buf. If buf is NULL it will be malloc'd
automatically. The parameter buf is returned (or the malloc'd buffer
if you passed NULL for buf). The parameter max specifies the maximum
length of the path including the terminating NULL character. NULL is
returned if any error occurs (such as malloc failing)
INPUTS
char *buf; buffer to place current directory path into or
NULL if you want getcwd to allocate one
int max; maximum size of buffer
RESULTS
char *path; returns allocated buffer if you passed NULL for
buf, else returns the first argument. Returns
NULL on error.
SEE ALSO
chdir
EXAMPLE
#include <stdio.h>
char buf[512];
main(int ac, char**av)
{
getcwd(buf, sizeof(buf));
printf("Current directory is: %s\n", buf);
return(0);
}
dice/getenv dice/getenv
FUNCTION
get environment variable (ANSI)
SYNTAX
#include <stdlib.h>
char *var = getenv(const char *name);
DESCRIPTION
getenv searches for and returns the ENV: enviroment variable
requested. getenv will cache variables so that requesting the same
variable repetitously does not allocate a new memory buffer. getenv
allocates a buffer for each variable returned, so you do not have to
copy the return value from getenv. This memory is free'd on program
exit. Do not attempt to free a getenv'd variable!!
INPUTS
char *name; Name of enviroment variable, on the Amiga this is
not case sensitive. On UNIX systems it is.
RESULTS
char *var; Contents of enviroment variable or NULL if the
variable could not be found.
EXAMPLE
#include <stdio.h>
#include <stdlib.h>
main(int ac, char**av)
{
char *dccopts = getenv("DCCOPTS");
if (dccopts)
printf("DCCOPTS = %s\n", dccopts);
else
printf("You do not have a DCCOPTS enviroment\
variable!\n");
return(0);
}
dice/getfnl dice/getfnl
FUNCTION
get file name list: scan directory, return list of files that match
the optional wildcard (DICE)
SYNTAX
#include <stdlib.h>
int n = getfnl(pat, buf, bufsize, attr);
const char *pat;
char *buf;
int bufsize;
int attr;
DESCRIPTION
getfnl scans the specified anchored AmigaDOS pattern and fills the
specified buffer (up to bufsize bytes) with file names separated by a
NULL character (\0), ending the list with a double NULL (\0\0).
getfnl returns the number of files/dirs in the buffer or -1 if there
is not enough room The pattern pat is an AmigaDOS pattern such as
"df0:#?.c". The parameter buf is a buffer of bufsize bytes. The
parameter attr determines what kinds of files are valid: 0 for
normal files only, 1 for files and directories
|| NOTE: getfnl exists for compatibility only; expand_args is a much
|| better function function to use if you want a list of files &
|| dirs.
INPUTS
const char *pat; pattern to scan for (anchored)
char *buf; buffer to put results in
int bufsize; size of buffer
int attr; attribes (0 or 1)
RESULTS
int n; number of file names in buffer or -1 on error
SEE ALSO
strbpl, expand_args
EXAMPLE
#include <stdio.h>
char Buf[4096];
main(int ac, char**av)
{
int n;
if (ac != 2)
{
puts("Expected an anchored wildcard such as '#?'");
exit(1);
}
n = getfnl(av[1], Buf, sizeof(Buf), 1);
{
char *ptr = Buf;
while (*ptr)
{
/* look for \0\0 */
puts(ptr);
ptr += strlen(ptr) + 1;
/* skip first \0 */
}
}
return(0);
}
dice/GetHead,GetTail,GetSucc,GetPred dice/GetHead,GetTail,GetSucc,GetPred
FUNCTION
Manipulate EXEC style lists (DICE)
SYNTAX
#include <lists.h>
struct Node *node = GetHead(list);
struct Node *node = GetTail(list);
struct Node *node = GetSucc(oldNode);
struct Node *node = GetPred(oldNode);
const struct Node *oldNode;
const struct List *list;
DESCRIPTION
These functions allow scanning of EXEC style lists (which are also
useful for many programs having nothing to do with EXEC). GetHead
returns the first node in a list or NULL if the list is empty;
GetTail returns the last node in a list or NULL if the list is empty;
GetSucc returns the next node in a list (given some intermediate
node) or NULL when we reach the end of the list GetPred returns the
previous node in a list before some intermediate node or NULL when we
reach the beginning of the list
|| NOTE: These are DICE functions and do not exist outside of DICE,
|| though they could be easily written.
INPUTS
struct List *list;
list to get head or tail node from
struct Node *oldNode;
node from which to get relative successor or
predecessor from
RESULTS
struct Node *node;
returned node or NULL
EXAMPLE
/*
* A simple symbol create/delete/list program.
* (Note: for a real symbol table you'd want
* to use hash tables)
*/
#include <lists.h> /* non-standard header file */
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
typedef struct List List;
typedef struct Node Node;
List SymList;
void AddSymbol(char *);
void DelSymbol(char *);
Node *FindSymbol(char *);
main()
{
char buf[256];
char symBuf[256];
short notDone = 1;
NewList(&SymList);
puts("(return for help)");
while (notDone)
{
printf("Enter Command: ");
fflush(stdout);
if ( fgets(buf, sizeof(buf), stdin) == NULL)
break;
switch(buf[0])
{
case 'a': if (sscanf(buf + 1,"%s",symBuf)== 1)
AddSymbol(symBuf);
break;
case 'd': if (sscanf(buf + 1,"%s",symBuf)== 1)
DelSymbol(symBuf);
break;
case 'l': { Node *node;
for (node = GetHead(&SymList); node;
node = GetSucc(node))
puts(node->ln_Name);
}
break;
case 'q': notDone = 0;
break;
default: puts("<return> -help ");
puts("a name-add symbol");
puts("d name-delete symbol");
puts("l -list symbols");
puts("q -quit");
break;
}
}
puts("bye!");
return(0);
}
void AddSymbol(name)
char *name;
{
Node *node;
if (FindSymbol(name))
{
puts("already exists!");
exit(1);
}
if (node = malloc(sizeof(Node)))
{
AddTail(&SymList, node);
node->ln_Name = strdup(name);
/* bad code, not checking */
/* for error result! */
}
}
void DelSymbol(name)
char *name;
{
Node *node;
if (node = FindSymbol(name))
{
Remove(node); /* take out of list */
free(node->ln_Name); /* free name */
free(node); /* free node last */
puts("ok");
}
else
{
puts("Couldn't find it!");
} }
Node * FindSymbol(name)
char *name;
{
Node *node;
for (node = GetHead(&SymList); node;
node = GetSucc(node))
{
if (strcmp(node->ln_Name, name) == 0)
return(node);
}
return(NULL);
}
dice/gets dice/gets
FUNCTION
get a line from stdin (ANSI)
SYNTAX
#include <stdio.h>
char *ptr = gets(buf);
char *buf;
DESCRIPTION
gets takes a line from stdin and places it into your buffer. A null
(\0) is placed in the buffer instead of the newline (\n). While the
function can be convenient, if your buffer is not large enough, you
loose. See fgets for a more reasonable function.
gets, puts
These functions strip newline on input, add newline on output.
gets works on stdin, puts on stdout.
fgets, fputs
These functions leave newlines alone on input, don't add to the
output. Any file pointer, including stdin and stdout may be
specified.
|| NOTE: Refer to the file_pointer manual page for general
|| information.
INPUTS
char *buf; buffer, must be able to maximum possible line
RESULTS
char *ptr; buf if all is well, or NULL if error or EOF
SEE ALSO
puts, fputs, fgets, fread, getc, fgetc
EXAMPLE
#include <stdio.h>
main()
{
char buf[128];
printf("Enter a line - ");
fflush(stdout);
if (gets(buf) == NULL) // Enter a long line to crash
exit(1);
printf("Your line was: %s\n", buf);
return(0);
}
dice/isalnum,isalpha,iscntrl,isdigit,isgraph,islower,isprint,ispunct,isspace,isupper,isxdigit
FUNCTION
Test a character for assorted attributes (ANSI)
SYNTAX
#include <ctype.h>
int r = isxxxxx(c);
int c;
|| NOTE: These are MACROS if you #include <ctype.h>, function calls
|| if you do not.
DESCRIPTION
These function return non-zero (true) if the test is true, and zero
(false) if not.
|| NOTE: When a non-zero value is returned, this value might be
|| anything other than zero. It is not necessarily a 1. It is
|| guaranteed to fit in a short, however, and still remain
|| non-zero.
||
|| Characters in the -1 to 255 range are valid inputs. Characters
|| less than -1 or larger than 255 are illegal and the results will
|| be random. If you are passing a CHAR, you must cast it to an
|| UNSIGNED CHAR first. EOF is a valid input, and always returns
|| false
isalpha Returns non-zero if the character is a letter in the alphabet
(a-z, A-Z).
isalnum Returns non-zero if the character is alphanumeric (a-z, A-Z,
0-9).
iscntrl Returns non-zero if the character is a control character (decimal
0 to 31).
isdigit Returns non-zero if the character is a digit ('0' through '9').
isgraph Returns non-zero if the character is printable and not a space.
isgraph is the same as isprint, but with the space character
excluded from the printable set.
islower Returns non-zero if the character is a lower case letter 'a' -
'z'.
isprint
Returns non-zero if the character is printable. isprint is the same
as isgraph, but with the space character included in the printable
set.
ispunct Returns non-zero if the character is any sort of punctuation,
including puntuation in the extended ASCII range. Basically, if
it is not a control character, alpha or a digit, it is
punctuation.
isspace Returns non-zero if the character is any sort of white space.
Included are space, shifted space, line feed (lf), form feed
(ff), carriage return (cr), tab, and vertical tab.
isupper Returns non-zero if the character is an upper case letter 'A'
-'Z'.
isxdigit Returns non-zero if the character is a valid hexadecimal digit
'0' - '9', 'a' - 'f', or 'A' - 'F'.
These macros use a lookup table. One table handles the eight
most common functions. A second table handles ispunct, isxdigit
and isprint. It saves space if you reference only one table.
There is space in the second table if you wish to add your own
tests (you'll have to recompile the library source code).
INPUTS
int c; character that we are checking
RESULTS
int r; 0 if the check failed, non-zero if the check is
true
SEE ALSO
tolower, toupper
#include <stdio.h>
#include <ctype.h>
main()
{
int c;
for( c=0; c<256; c++) {
if( (c & 31) == 0 ) /* 32 per line */
printf("\n%02x: ", c);
if( isprint( c ) )
printf("%c", c ); /* character */
else
printf("%c", 127 ); /* placeholder */
}
printf("\n");
for( c=0; c<256; c++) {
if( (c & 31) == 0 ) /* 32 per line */
printf("\n%02x: ", c);
if( ispunct( c ) )
printf("x"); /* true */
else
printf("-"); /* false */
}
printf("\n");
return( 0 );
}
dice/isatty dice/isatty
FUNCTION
Test if a a file descriptor is a TTY (UNIX)
SYNTAX
#include <ctype.h>
int r = isatty(fd); int fd;
DESCRIPTION
isatty returns TRUE (1) if the file descriptor is associated with a
console, FALSE (0) if not, or -1 if an error condition occurs (such
as illegal file descriptor).
|| NOTE: The standard input (0), standard output (1), and standard
|| error (2) can all return different values for isatty depending on
|| how the program is redirected. A program whose standard in and
|| standard out is redirected may still have a standard error that is
|| connected to the console. Refer to the file_descriptor manual page
|| for general information. Unlike file pointers and file handles,
|| the file descriptor is checked for validity and will simply return
|| an error if illegal.
INPUTS
int fd; file descriptor
RESULTS
int r; result, 1 if a tty, 0 if not, or -1 if error
SEE ALSO
close, creat, fcntl, fdtofh, getfh, ioctl, lseek, mkdir, open, read,
rmdir, unlink, write
dice/ioctl dice/ioctl
FUNCTION
IO control on file descriptor (UNIX)
SYNTAX
#include <fcntl.h>
int r = ioctl(fd, req, parg1, parg2);
int fd;
int req;
int *parg1;
int *parg2;
DESCRIPTION
ioctl executes an IO control on the file descriptor. Currently no IO
controls are implemented.
INPUTS
int fd; file descriptor
int req; request from <ioctl.h>
int *parg1; address of argument #1
int *parg2; address of argument #2
RESULTS
int r; result, error if < 0.
SEE ALSO
close, creat, fcntl, fdtofh, getfh, isatty, lseek, mkdir, open, read,
rmdir, unlink, write
dice/localtime dice/localtime
FUNCTION
convert time into broken down time (ANSI)
SYNTAX
#include <time.h>
struct tm *tp = localtime(&t);
time_t t;
DESCRIPTION
localtime takes the address of a time_t variable and breaks up the
time into component parts, storing them in a static tm structure.
The address of this structure is returned. Since the broken up time
is stored into a static structure, the structure will get overwritten
on the next call to localtime. The fields of the tm structure are:
struct tm {
int tm_sec; /* 0-59 */
int tm_min; /* 0-59 */
int tm_hour; /* 0-23 */
int tm_mday; /* 1-31 */
int tm_mon; /* 0-11 */
int tm_year; /* n+1900 */
int tm_wday; /* (sun)0-6*/
int tm_yday; /* 0-366 */
int tm_isdst; /* is daylight savings? */
/* (the is daylight flag is not implemented by DICE) */
};
INPUTS
time_t *t; pointer to a time_t
RESULTS
struct tm *tp; pointer to a struct tm structure filled out
according to the passed time.
SEE ALSO
time, asctime, strftime, ctime, clock
EXAMPLE
/*
* Note that it is much easier to format time/date
* strings with strftime().
*/
#include <stdio.h>
#include <time.h>
main()
{
time_t t = time(NULL);
struct tm *tp = localtime(&t);
printf("The time is %02d:%02d:%02d\n", tp->tm_hour,
tp->tm_min, tp->tm_sec);
return(0);
}
dice/LockAddr,LockAddrB,TryLockAddr,TryLockAddrB,UnlockAddr,UnlockAddrB
FUNCTION
LockAddr: Gain Exclusive, Fast semaphore (bit 0)
LockAddrB: Gain Exclusive, Fast semaphore (bit n 0-7)
TryLockAddr: Non- Blocking version of LockAddr
TryLockAddrB: Non-Blocking version of LockAddrB
UnlockAddr: Release exclusive semaphore, bit 0
UnlockAddrB: Release exclusive semaphore, bit n 0-7 (DICE)
SYNTAX
void LockAddr(lck);
void LockAddrB(bitno, lck);
int r = TryLockAddr(lck);
int r = TryLockAddrB(bitno, lck);
void UnlockAddr(lck);
void UnlockAddrB(bitno, lck);
long lck[2];
DESCRIPTION
These are custom DICE functions used for inter-task locking
semaphores in programs that need such functions. These routines are
somewhat faster than standard Amiga semaphore routines and take less
memory, though at the cost of DICE specific. To use an inter-task
lock one first initializes an lck array to 0's. The entry long
lck[2]; is an array of two longwords that the lock routines will use
to do their stuff. This array should be zero'd only once at program
initialization time (the master task before any other tasks are
created that use it). Each lck array may hold up to 8 locks, hence
the LockAddrB calls. The non-B calls use lock #0 for simplicity. For
simplicity we will only discuss non-B calls.
To gain a lock you may call LockAddr with the address of the lck
array (which, being an array, does not need the & in the call). This
routine will not return until the lock can be obtained. You may also
use TryLockAddr to attempt to gain a lock. The return value is: -1
if the command is unable to obtain the lock (that is, it is in use),
1 if the lock has been obtained. To release an obtained lock you
call UnlockAddr(lck).
## WARNING: DO NOT RELEASE A LOCK YOU DO NOT HAVE!
INPUTS
long *lck; a pointer to two longwords, initially zero'd
-int bitno; lock # ... up to 8 independant locks exist for
each lck structure
RESULTS
int r; (TryLock only), -1 on failure, 1 on success.
EXAMPLE
/*
* This program obtains a lock based at a public
* message port and holds it for ten seconds before
* releasing it. The public message port is left
* in memory (but only exists once no matter how
* many programs you run).
*
* To test locking, open up two or more CLI's and run
* the program simultaniously (or as close as your
* fingers can make it) two or more times. Only one
* program will 'have' the lock at a time.
*
* we use AllocMem() so the port survives the program
*/
#include <exec/types.h>
#include <exec/ports.h>
#include <exec/memory.h>
#include <stdio.h>
#include <stdlib.h>
#include <assert.h>
typedef struct
{
struct MsgPort Port;
long Lock[2];
}
MyPort;
extern void *FindPort();
extern void *CreatePort();
extern void *AllocMem();
MyPort *Port;
short HaveLock;
int brk()
{
if (HaveLock)
UnlockAddr(Port->Lock);
return(1); /* abort */
}
main()
{
char *portName = "Lock-Test";
onbreak(brk);
Forbid();
if ((Port = FindPort(portName)) == NULL)
{
MyPort *port;
port = AllocMem(sizeof(MyPort) + strlen(portName)
+ 1, MEMF_PUBLIC | MEMF_CLEAR);
assert(port);
port->Port.mp_Node.ln_Name = (char *)(port + 1);
port->Port.mp_Node.ln_Type = NT_MSGPORT;
strcpy(port->Port.mp_Node.ln_Name, portName);
AddPort(port);
Port = port;
}
Permit();
puts("getting lock");
LockAddr(Port->Lock);
HaveLock = 1;
puts("Got the lock!, sleeping for 10 seconds");
sleep(10);
UnlockAddr(Port->Lock);
HaveLock = 0;
puts("released lock");
return(0);
}
dice/log,flog dice/log,flog
FUNCTION
log: return the log of a double, base e (ANSI)
flog: return the log a float, base e (ANSI)
LIBRARY
m.lib
SYNTAX
#include <math.h>
double a = log(b);
double b;
float c = flog(d);
float d;
DESCRIPTION
The former command returns the log of the double quantity, base e;
the latter returns the log of the float quantity, base e.
INPUTS
double b; double floating point value float d; float
floating point value
RESULTS
double a; result double floating point value float c;
result float floating point value
SEE ALSO
acos, asin, atan, cos, exp, fabs, log10, pow, sin, sqrt, tan facos,
fasin
dice/log10,flog10 dice/log10,flog10
FUNCTION
log10: return the logarithm of a double, base 10 (ANSI)
flog10: return the logarithm of a float, base 10 (ANSI)
LIBRARY
m.lib
SYNTAX
#include <math.h>
double a = log10(b);
double b;
float c = flog10(d);
float d;
DESCRIPTION
log10 returns the log of a double quantity, base 10; flog10 returns
the log of the floating point quantity, base 10.
INPUTS
double b; double floating point value
float d; float floating point value
RESULTS
double a; result double floating point value
float c; result float floating point value
SEE ALSO
acos, asin, atan, cos, exp, fabs, log, pow, sin, sqrt, tan facos,
fasin
EXAMPLE
/*
* compile with the math library -lm
*/
#include <math.h>
#include <stdio.h>
main()
{
{
double a = log10(0.25);
printf("log10 0.25 = %lf\n", a); /* -0.6021 */
}
{ /* less accuracy */
float a = flog10(0.25);
printf("log10 0.25 = %lf\n", (double)a);
}
return(0);
}
dice/lseek dice/lseek
FUNCTION
seek within a file descriptor (UNIX)
SYNTAX
#include <fcntl.h>
long newpos = lseek(fd, offset, how)
int fd;
long offset;
int how;
DESCRIPTION
lseek changes where the file descriptor points to within the open
file. You may specify an offset relative to the beginning of the
file, the current position in the file, or the end of the file:
Val : Purpose
====+=========================================================
0 : absolute offset (relative to the beginning of the file)
----+---------------------------------------------------------
1 : offset relative to the current position in the file
----+---------------------------------------------------------
2 : offset relative to the end of the file
----+---------------------------------------------------------
Negative offsets may be specified when relative modes are used. The
function lseek returns the new position in the file relative to the
beginning of the file (i.e. an absolute offset).
|| NOTE: offsets are relative. So, for example, if you want to seek
|| to the fourth character from the end of the file you would
|| lseek(fd, -4L, 2);. Refer to the file_descriptor manual page for
|| general information. Unlike file pointers and file handles, the
|| file descriptor is checked for validity and will simply return an
|| error if illegal.
INPUTS
int fd; file descriptor
long offset; offset relative to how
int how; 0 = rel beginning, 1 = rel middle, 2 = rel end
RESULTS
int newpos; new position in file (absolute) or < 0 if error
SEE ALSO
close, creat, fcntl, fdtofh, getfh, ioctl, isatty, mkdir, open, read,
rmdir, unlink, write
EXAMPLE
See open for an example.
dice/main dice/main
FUNCTION
main program entry (ANSI)
SYNTAX
#include <anything.h>
int main(int argc, char **argv)
{
/* your pride and joy goes here */
}
DESCRIPTION
The main routine is the entry point called after normal
initialization of c.lib and the program enviroment is done by the
startup module (c.o) and _main routine (in c.lib). Under ANSI C main
is expected to return an integer exit code. You can no longer simply
fall through without returning any value. Returning an exit code
from your main routine is exactly the same as exiting with it.
|| NOTE: Any program run from the WORKBENCH uses a different access
|| point. Specifically, a program run from the WORKBENCH will run
|| wbmain instead of main. Please refer to the manual page for
|| wbmain for WORKBENCH operation.
If you do not supply a wbmain a dummy wbmain will be supplied by the
library which simply exits out of the program.
INPUTS
int argc; number of arguments
char *argv; array pointer to arguments
SEE ALSO
wbmain, _main, exit, _exit
EXAMPLE
/* Print back out all given arguments */
#include <stdio.h>
int main(int ac, char**av)
{
int i;
for (i = 0; i < ac; ++i) {
printf("Arg #%d = %s\n", i, av[i]);
}
return(0);
}
dice/_main dice/_main
FUNCTION
main program entry, bypass standard c.lib initialization (DICE)
SYNTAX
#include <the_world.h>
void _main(int arglen, char *argptr)
{
/* your very special code goes here */
}
DESCRIPTION
The _main entry point is called by the startup module (c.o).
Normally _main is part of c.lib and does stdio and other
initialization before calling the user main routine. _main is
responsible for opening the stderr channel as well. However, if you
specify your own _main you will overide the c.lib version. Normally
you either fall through or _exit from _main. A programmable can use
the _main entry point when the executable uses nothing but system
library routines. That is, you make no calls to stdio functions such
as puts, printf, etc., to low level IO routines such as open, close,
read, etc., or malloc or any routine that uses malloc. Self contained
routines such as strcpy may still be called, and, of course, you may
open any libraries you wish and make library calls. Since the
auto-library openning and closing is done by the startup module
(c.o), "dos.library" will still be opened for you automatically if
you make any DOS calls.
Using the _main entry point usually results in a substantially
smaller executable because stdio and other library routines
referenced by the c.lib. _main and exit are never referenced and thus
never become part of the executable. It is NOT SUGGESTED that
beginning C programmers use the _main entry point.
|| NOTE: _main is called by the startup module whether the program
|| was run from the CLI or the WORKBENCH. You must detect which
|| yourself and also deal with the WORKBENCH message yourself.
int argc; number of arguments
char *argv; array pointer to arguments
SEE ALSO
_exit, main, exit
EXAMPLE
/*
** This program comes in at under 600 bytes.
*/
_main()
{
Write(Output(), "UG!\n", 4);
_exit(0);
}
dice/malloc dice/malloc
FUNCTION
allocate memory, the memory is NOT automatically cleared (ANSI)
SYNTAX
#include <stdlib.h>
void *ptr = malloc(bytes);
size_t bytes;
DESCRIPTION
malloc allocates the specified number of bytes of memory. The
returned pointer is longword aligned; malloc returns NULL if the
memory could not be allocated.
|| NOTE: Unlike calloc, malloc does not zero the memory before it
|| returns.
INPUTS
size_t bytes; number of bytes to allocate
RESULTS
void *ptr; pointer to base of allocated memory. The memory
is not zero'd.
SEE ALSO
calloc, strdup
dice/memcmp dice/memcmp
FUNCTION
compare two memory buffers (ANSI)
SYNTAX
#include <string.h>
int r = memcmp(s1, s2, bytes)
void *s1;
void *s2;
size_t bytes;
DESCRIPTION
memcmp compares two memory buffers. A byte by byte unsigned
comparison is done. When a comparison fails and the byte in s1 is
less than the byte in s2 then -1 is returned. If the byte in s1 is
greater than the byte in s2 then 1 is returned. If the count is
exhausted and all comparisons succeed then 0 is returned indicating
the two buffers are the same.
INPUTS
void *s1; pointer to first buffer
void *s2; pointer to second buffer
size_t bytes; size of each buffer
RESULTS
int r; -1 if buf s1 < buf s2, 0 if buf s1 == buf s2, 1
if buf s1 > buf s2.
SEE ALSO
memset, setmem, bzero, clrmem, bcopy, bcmp, movmem, memcpy, memmove
EXAMPLE
#include <stdlib.h>
#include <assert.h>
main()
{
unsigned char buf1[5] = {9, 10, 1, 12}; /* 1,729 */
unsigned char buf2[5] = {9, 10, 1, 12}; /* 1,729 */
int r;
r = memcmp(buf1, buf2, 4);
assert(r == 0);
buf1[2] = 0;
r = memcmp(buf1, buf2, 4);
assert(r < 0);
buf1[2] = 42;
r = memcmp(buf1, buf2, 4);
assert(r > 0);
return(0);
}
dice/memcpy,memmove,movmem,bcopy dice/memcpy,memmove,movmem,bcopy
FUNCTION
memcopy: copy memory, ANSI, overlapped memory buffers illegal
memmov: copy memory, ANSI, works with overlapped memory buffers
movmem: copy memory, UNIX, works with overlapped memory buffers
bcopy: copy memory, UNIX, works with overlapped memory buffers
SYNTAX
#include <string.h>
void *ptr = memcpy(d, s, bytes);
void *ptr = memmove(d, s, bytes);
void *ptr = movmem(s, d, bytes);
void *ptr = bcopy(s, d, bytes);
void *d;
void *s;
size_t bytes;
DESCRIPTION
These functions copy memory from one region to another. Unlike
string routines these functions do not stop the copy when a NULL is
encountered.
## WARNING: Be careful about argument ordering. Some calls take the
## source buffer first and other calls take the destination buffer
## first.
The ANSI committee opted for a destination, source ordering rather
than the more logical source, destination ordering. Thus, many
programmers will use the non-standard movmem call instead of the ANSI
memmove call. The ANSI function 'memcpy' as defined by the ANSI
standard cannot handle overlapped memory areas. The Amiga
implementation can but you should remember this if you intend to port
your code.
|| NOTE: DICE's memory move optimizes the copy using movem when
|| possible, yielding very fast memory copies for large buffers. The
|| UNIX bcopy call exists for compatibility purposes and should not
|| be used with new programs.
INPUTS
void *s; source buffer
void *d; destination buffer
RESULTS
void *ptr; pointer to the destination buffer(d)
SEE ALSO
memset, setmem, bzero, clrmem, cmpmem, memcmp
EXAMPLE
/*
* This example copies the entire buffer, not just
* the part containing the string. Normally one just
* uses string routines.
*/
#include <string.h>
#include <assert.h>
main()
{
char s[16];
char d[16];
void *p;
strcpy(s, "This is a test");
p = movmem(s, d, sizeof(s));
assert(p == d);
puts(d);
strcpy(s, "Googolplex");
p = bcopy(s, d, sizeof(s));
assert(p == d);
puts(d);
strcpy(s, "EchoBeko");
p = memcpy(d, s, sizeof(s));
assert(p == d);
puts(d);
strcpy(s, "GakFuBar");
p = memmove(d, s, sizeof(s));
assert(p == d);
puts(d);
return(0);
}
dice/memset,setmem,clrmem,bzero dice/memset,setmem,clrmem,bzero
FUNCTION
memset: ANSI, set memory buffer to a byte value
setmem: UNIX, set memory buffer to a byte value
clrmem: DICE, zero out a memory buffer
bzero: UNIX, zero out a memory buffer
SYNTAX
#include <string.h>
void *ptr = memset(buf, c, n);
void *ptr = setmem(buf, n, c);
void *ptr = clrmem(buf, n);
void *ptr = bzero(buf, n);
void *buf;
int c;
size_t n;
DESCRIPTION
These functions fill a memory buffer with the specified character c.
C is converted to an unsigned chararacter by the fill routine before
beginning the fill. N bytes are filled.
## WARNING: Again, watch out for argument ordering, especially for
## the ANSI memset call.
The ANSI committee chose bizarre call ordering so there is another
defacto standard call called setmem. The function bzero exists for
UNIX compatibility, and clrmem is yet another call (this time
introduced by DICE--sorry!). memset and setmem are the most portable
calls.
INPUTS
void *buf; pointer to buffer to fill
int c; character to copy into buffer
(setmem, memset) size_t n;
# of bytes to fill
RESULTS
void *ptr; pointer to buffer (== buf).
SEE ALSO
malloc, calloc, strdup, movmem, cmpmem
EXAMPLE
#include <string.h>
#include <assert.h>
#include <stdlib.h>
main()
{
char buf[32];
char *b;
b = setmem(buf, 32, 0);
assert(b == buf);
b = setmem(buf, 4, 'a');
b = memset(buf + 4, 'b' , 4);
puts(buf); /* aaaabbbb */
return(0);
}
dice/mkdir dice/mkdir
FUNCTION
create a directory (UNIX)
SYNTAX
#include <stdio.h>
int error = mkdir(dirname)
char *dirname;
DESCRIPTION
mkdir creates a new directory. It returns 0 if successful, -1 if not
(with errno set to an error code).
INPUTS
char *dirname; filename of directory to create
RESULTS
int r; 0 if no error, < 0 if error
SEE ALSO
close, creat, fcntl, fdtofh, getfh, ioctl, isatty, lseek, mkdir,
open, read, rmdir, unlink, write
EXAMPLE
main()
{
int r;
r = mkdir("T:tmpdir");
if (r == 0)
puts("Created T:tmpdir successfully");
else
puts("Unable to create directory T:tmpdir");
}
dice/_mods,_modu dice/_mods,_modu
FUNCTION
signed/unsigned long modulus 32 (DICE)
DESCRIPTION
These are assembly functions that DICE uses whenever it needs to do a
long modulus. The functions are not callable from C.
INPUTS
D0 32 bit signed/unsigned integer
D1 32 bit signed/unsigned integer
RESULTS
D0 Remainder of D0 divided by D1
SEE ALSO
_divs, _divu, _muls, _mulu
dice/_muls,_mulu dice/_muls,_mulu
FUNCTION
signed/unsigned long multiply (DICE)
DESCRIPTION
These are assembly functions that DICE uses whenever it needs to do
long multiplication. They are not callable from C.
INPUTS
D0 32 bit signed/unsigned integer
D1 32 bit signed/unsigned integer
RESULTS
D0 D0 multiplied by D1
SEE ALSO
_divs, _divu, _mods, _modu
dice/onbreak dice/onbreak
FUNCTION
Set special ^C handler (AmigaDOS)
SYNTAX
typedef int (*fptr)();
fptr oldfunc = onbreak(newfunc);
fptr newfunc;
DESCRIPTION
onbreak sets a special function to handle ^C. It takes a pointer to
this function and returns a pointer to the previous onbreak function,
if any. When ^C is hit, the special onbreak function is called
before any other action. If the onbreak function returns a non-zero
value, ^C aborts the program like it usually does. If the function
returns 0, however, the ^C is completely ignored.
INPUTS
newfunc pointer to function or NULL
RESULTS
fptr oldfunc; pointer to previous onbreak function
SEE ALSO
atexit
EXAMPLE
/*
* Note: The reentrancy check is needed because of both
* the puts and the sleep() call.
*/
#include <stdio.h>
#include <stdlib.h>
int brk()
{
static short cnt = 0; /* check for reentrancy */
if (cnt) /* if not 0 then reentered! */
return(0);
++cnt;
puts("Nah Nah, you can't break me!");
sleep(1);
--cnt;
return(0);
}
int main()
{
short i;
onbreak(brk);
puts("Hit ^C while I loop from 1 to 100.");
sleep(2);
for (i = 1; i <= 100; ++i)
printf("Loop, counting, count = %d\n", i);
return(0);
}
dice/open dice/open
FUNCTION
open a file (UNIX)
SYNTAX
#include <fcntl.h>
int fd = open(name, modes);
char *name;
int modes;
DESCRIPTION
open opens a file of the specified name using the specified modes.
The combinations yield different results as described below:
O_RDONLY : open file for reading only
----------+-----------------------------------------------------------------
O_WRONLY : open file for writing only
----------+-----------------------------------------------------------------
O_RDWR : open file for reading and writing
----------+-----------------------------------------------------------------
O_NDELAY : open file non-blocking (not implemented)
----------+-----------------------------------------------------------------
O_APPEND : open file for writing only and force all writes to append to
: the file regardless of the current seek position. open is a
: lower-level construct than the more standard fopen.
----------+-----------------------------------------------------------------
O_CREAT creates the file if it does not exist; O_TRUNC truncates the
file if it does exist; O_EXCL is used only with O_CREAT and if the
file already exists the open will fail; O_BINARY opens the file for
binary reading and writing, vs text. This flag is ignored by DICE
since there is no difference on the Amiga. However, on Messy-DOS
systems, CR-LF must be converted to an LF when reading text files.
open returns a descriptor (>= 0) or error (< 0) on failure.
|| NOTE: Refer to the file_descriptor manual page for general
|| information. Unlike file pointers and file handles, the file
|| descriptor is checked for validity and will simply return an error
|| if illegal.
INPUTS
char *name; filename to open
long modes; modes to open the file with
RESULTS
int fd; A file descriptor if >= 0, an error if < 0.
SEE ALSO
close, creat, fcntl, fdtofh, fopen, ioctl, isatty, lseek, mkdir,
read, rmdir, unlink, write
EXAMPLE
#include <fcntl.h>
#include <assert.h>
main()
{
int fd, r;
fd = open("T:xx", O_WRONLY|O_CREAT|O_TRUNC);
assert(fd >= 0);
close(fd);
fd = open("T:xx", O_CREAT|O_EXCL|O_TRUNC|O_WRONLY);
assert(fd < 0); /* will fail, file already exists */
remove("T:xx");
fd = open("T:xx", O_CREAT|O_TRUNC|O_WRONLY);
assert(fd >= 0); /* will work */
write(fd, "FuBar-", 6);
lseek(fd, 0L, 0); /* seek back to start of file */
r = write(fd, "XxXxx", 5);
assert(r == 5);
close(fd);
fd = open("T:xx", O_APPEND|O_WRONLY);
assert(fd >= 0);
write(fd, "FuBar\n", 6);
close(fd);
printf("type t:xx should return \"XxXXX-FuBar\"\n");
return(0);
}
dice/perror dice/perror
FUNCTION
output error message associated with errno and text to stderr (ANSI)
SYNTAX
#include <stdio.h>
void perror(str);
const char *str;
DESCRIPTION
perror outputs the specified string, a colon, and the error number
and error message associated with the current value of errno to
stderr, ending with a newline. Using perror is a common way to
generate error messages due to IO failures.
INPUTS
char *str; string message to include in error output
EXAMPLE
#include <stdio.h>
main()
{
FILE *fp = fopen("T:DoesNotExist", "r");
if( fp ) {
puts("T:DoesNotExist is not supposed to exist!");
exit(1);
}
perror("fopen");
return(0);
}
dice/pow,fpow dice/pow,fpow
FUNCTION
pow: return one double to the power of another (ANSI)
fpow: return one float to the power of another (ANSI)
LIBRARY
m.lib
SYNTAX
#include <math.h>
double a = pow(b, bp);
double bp;
double b;
float c = flog(d, dp);
float dp; float d;
DESCRIPTION
pow returns one double to the power of another; fpow returns one
float to the power of another.
INPUTS
double b; double floating point value (base)
double bp; double floating point value (exponent)
float d; float floating point value (base)
float dp; float floating point value (exponent)
RESULTS
double a; double floating point value
float c; float floating point value
SEE ALSO
acos, asin, atan, cos, exp, fabs, log, log10, pow, sin, sqrt, tan
facos, fasin
EXAMPLE
/*
* compile with the math library -lm
*/
#include <math.h>
#include <stdio.h>
main()
{
{
double a = pow(0.25, 4.0);
printf("pow 0.25 ^^ 4.0 = %lf\n", a);
/* 0.0039 */
}
{ /* less accuracy */
float a = fpow(0.25, 4.0);
printf("pow 0.25 ^^ 4.0 = %lf\n", (double)a);
}
return(0);
}
dice/printf,fprintf,sprintf,vprintf,vfprintf,vsprintf
FUNCTION
formatted output to stdout, file pointer, or buffer (ANSI)
SYNTAX
#include <stdio.h>
#include <stdarg.h> /* for v[f/s]printf() only */
int n = printf(fmt, ...);
int n = fprintf(fp, fmt, ...);
int n = sprintf(buf, fmt, ...);
int n = vprintf(fmt, argvect);
int n = vfprintf(fp, fmt, argvect);
int n = vsprintf(buf, fmt, argvect);
FILE *fp;
char *fmt;
char *buf;
va_list argvect;
DESCRIPTION
These functions offer formatted printing in various flavors. printf
and vprintf output to stdout; fprintf and vfprintf output to a file
pointer (fp); sprintf and vsprintf output to a character buffer. All
routines return the number of characters written if successful, a
negative number if not. Only sprintf and vsprintf are limited in
terms of output size (it cannot exceed the buffer you give it). The
common argument to all routines is the format specifier. The format
specifier is scanned to determine how to handle the arguments to the
call (or the argument list for vfprintf/vsprintf). Characters are
copied to the output until a % is encountered. %% indicates a literal
'%' character. Otherwise, the % is followed by a control sequence
that tells printf how to output the corresponding argument. The
quantity is output and the scan continues until the end of the format
string. The % formats are interpreted as follows:
%[flags][#[.#]][modifier]<conversion-specifier>
Items in brackets are optional. After the %, zero or more flags may
be specified. Then, an optional integer which represents the minimum
field width for the object may also be specified. If an integer is
specified it may be followed by a period and another integer that
represents that precision with which a number is printed. Zero or
more modifiers may then be specified followed by a mandatory
conversion specifier.
Either or both integers (#[.#]) may be specified as a '*', as in
"%*d", specifying that the minimum field width and/or precision is
specified as an integer in the argument that occurs before the
conversion object. For example, printf("--%*d--\n", 10, 23); would
print the number 23 right justified in a field 10 characters wide.
FLAGS
-----
Minus (-) Left justify text within the field.
<space> This flag places a blank in front of positive signed numbers, and
a minus in front of negative numbers. This option allows columns
of positive and negative numbers to line up.
Plus (+) Cuase a plus sign to be placed before a positive result. A minus
sign is always placed before a negative result.
Pound (#) Format output acording to the type of input. e, E, f, F always
retains the decimal point. g, G always retains the decimal
point, and trailing zeros are kept. x and X print '0x' and '0X'
respectively before the number (except that this is not currently
implemented by DICE).
0 Pad columns with zeros instead of spaces. Ignored if a precision
is specified or if the '-' flag is specified.
MODIFIERS
---------
h Indicates the corresponding integer argument is a short or an
unsigned short (stands for "half-size"). Affects scanf(), but
since DIEC uses 32 bit integers, has no effect on printf().
l Indicates the corresponding integer argument is a long or
unsigned long. Also indicates floating point argument is a
double (else is a float). Under DICE this flag is superfluous for
integers, but for portability reasons you want to specify it when
an argument is explicitly a long.
CONVERSION SPECIFIER
--------------------
c Output integer as a character.
d Output a signed integer.
e Output a double quantity in exponential form. The precision
specifies the number of digits beyond the decimal point to print,
ie: [-]d.dddddde+/-dd.
E Upper case version of e.
f Output a double quantity. The precision specifies the number of
digits beyond the decimal point to print, ie: [-]d.dddddd
g Output a double quantity using either the 'e' or 'f' form,
depending on the exponent.
G Output a double quantity using either the 'E' or 'f' form,
depending on the exponent.
i Same as 'd', but less portable.
n The argument is a pointer to an integer which is used to set the
integer to the bytes written out so far. This is especially
useful with sprintf todetermine where a particular part of the
format begins in the output buffer.
o The unsigned integer quantity is converted to ASCII-octal.
p The pointer is printed (basically the hexadecimal address is
printed).
s The NULL-terminated string represented by the character pointer
is printed.
u The unsigned integer quantity is converted to ASCII-decimal.
x The unsigned integer quantity is converted to ASCII-hex using
'0'-'9', 'a'-'f'.
X The unsigned integer quantity is converted to ASCII-hex using
upper case 'A'-'F' instead of lower case.
INPUTS
FILE *fp; file pointer (fprintf, vfprintf)
char *fmt; format string, e.g. "Answer is %d\n"
char *buf; buffer (sprintf, vsprintf)
va_list argvect; arg list (vprintf, vfprintf, vsprintf)
RESULTS
int n; Number of characters written if successful, a
negative number if not. For sprintf and vsprintf
the NULL character at the end of the string is
NOT included in the count.
SEE ALSO
puts, fputs, fwrite
EXAMPLE
/*
** Example using most printf conversion specifiers.
** Compile with -lm for the math functions to operate.
*/
#include <stdio.h>
#include <stdarg.h>
void test_varargs(); /* Always use function prototypes */
main()
{
char buf[256];
int n, i;
printf("Normal: ab%c %03d %03o $%p Fu%s %u $%x $%8X $%08lX\n",
'c', 43, 11, buf, "Bar",32094,4095,4095,4095 );
printf("Math: Double: %le Float: %lf Formatted Float: %2.2lf\n",
1.23E-2, 1.23E-2, 1.257 );
printf("%9s\n", "<-"); /* Specify 9 chracter field width */
printf("%*s\n", 9, "<-"); /* Indirect specification */
n = sprintf(buf, "Save %n%s", &i, "the whales");
puts(buf);
printf("String is %d+1 bytes long, with a %%n token at %d.\n", n,
i);
fprintf(stdout, "\nThis is a call to %s\n", "fprintf");
test_varargs("%d %d %d ", 1, 2, 3);
return(0);
}
void test_varargs(ctl, ...)
char *ctl;
{
va_list va;
int n;
va_start(va, ctl);
n = vprintf(ctl, va);
printf("<- %d chars written\n", n);
va_end(va);
}
dice/putchar dice/putchar
FUNCTION
output character to stdout (ANSI)
SYNTAX
#include <stdio.h>
int r = putchar(c); /* MACRO */
DESCRIPTION
putchar outputs a character to stdout, returning the output character
unless an error occured. If an error occured then EOF is returned.
|| NOTE: Refer to the file_pointer manual page for general
|| information.
INPUTS
int c; character to output, 0 to 255
RESULTS
int r; same as c unless error occured in which case EOF.
SEE ALSO
putc, fputc, fread, fwrite, getc, getchar
EXAMPLE
/*
* copy stdin to stdout using getchar/putchar. Normally
* one uses fread/fwrite, but I'll save that for the
* fread manual page. Note that I output the initial
* message to stderr so it does not get stuck into stdout
* in case the user has redirected stdout.
*
* See getc manual page for equivalent example using
* getc/putc
*/
#include <stdio.h>
main()
{
int c;
fputs("Type a couple of lines, then ^\\ (EOF)\n",
stderr);
while ((c = getchar()) != EOF)
{
putchar(c);
}
return(0);
}
dice/qsort dice/qsort
FUNCTION
sort an array of objects (ANSI)
SYNTAX
#include <stdio.h>
#include <stdlib.h>
(void) qsort(array, numElem, elemSize, compare_func)
void *array;
size_t numElem;
size_t elemSize;
int (*comp_func)(const void *arg1, const void *arg2);
DESCRIPTION
qsort sorts numElem elements in an array based at array. Each element
is elemSize bytes long. When a comparison is required, qsort calls
the passed compare_func function pointer with a pointer to the two
elements being sorted. DICE currently implements qsort with a simple
merge sort algorithm, using relatively slow movmems to avoid having
to allocate much additional storage. Very little stack is used.
Traditional qsort employs a stack based quick-sort algorithm that
might use a massive amount of stack.
INPUTS
void *array; pointer to base of array of objects
size_t numElem; number of elements in the array
size_t elemSize; size, in bytes, of each element
int (*comp_func)()
function pointer to compare function given
pointers to two of the elements
EXAMPLE
#include <stdio.h>
#include <stdlib.h>
#define NUM_GENIUS 8
char *StrList[NUM_GENIUS] =
{
"Euler", "Einstein", "Pascal", "Zeno",
"Godel", "Leibniz", "Euclid", "Von Neumann"
};
my_comp(s1, s2)
char **s1; char **s2;
{
return(strcmp(*s1, *s2));
}
main()
{
short i;
qsort(StrList, NUM_GENIUS, sizeof(char *), my_comp);
for (i = 0; i < NUM_GENIUS; ++i)
printf("%d %s\n", i, StrList[i]);
return(0);
}
dice/raise dice/raise
FUNCTION
raise a signal (cause an 'interrupt' synchronously) (ANSI)
SYNTAX
int r = raise(signo);
int signo;
DESCRIPTION
raise causes a signal to occur and the appropriate action to be
taken. It returns 0 on success, -1 if the signo is invalid (outside
the range of allowed signals). When you raise a signal, the signal
is set back to its default vector before the handler is called.
Thus, if you are allowing multiple signals to occur you MUST restore
the signal vector with signal from your signal handler before it
returns.
INPUTS
int signo; signal to cause
RESULTS
int r; 0 on success, -1 if signo is out of range.
SEE ALSO
signal
EXAMPLE
/*
* prints the numbers 0 to 99, except only gets
* to 50 because we 'cause' a ^C.
*/
#include <signal.h>
main()
{
short i;
for (i = 0; i < 100; ++i) {
printf("i = %d\n", i);
if (i == 50)
raise(SIGINT);
}
return(0);
}
dice/rand dice/rand
FUNCTION
return pseudo-random number (ANSI)
SYNTAX
#include <stdio.h>
#include <stdlib.h>
int n = rand(void);
(void) srand(seed)
unsigned int seed;
DESCRIPTION
rand returns a random number as a positive integer ranging from 0 to
RAND_MAX. RAND_MAX is defined in stdlib.h and is at least 32767.
DICE implements it as 2147483647 == 0x7FFFFFFF.
The initial seed used to generate the pseudo-random sequence is 1,
but may be reinitialized to any number you desire using srand. rand
is guaranteed to return the same sequence for the same seed.
INPUTS
none
RESULTS
int n; returned by rand(), this number will be a
positive integer.
SEE ALSO
srand
EXAMPLE
#include <stdio.h>
#include <stdlib.h>
main(int ac, char**av)
{
short i;
short j;
if (ac == 2) {
int seed =
strtol(av[1], NULL, 0);
srand(seed);
printf("using seed = %d\n",
seed);
}
else
puts("using seed = 1");
for (i = 0; i < 10; ++i) {
int n = rand();
printf("Random number: %08lx\t(%d)\n", n, n);
}
for (i = 0; i < 31; ++i) {
int isone = 0;
long mask = 1 << i;
for (j = 0; j < 32767; ++j) {
if (rand() & mask) ++isone;
}
printf("bit %d %5d:%-5d (deviation %d)\n", i,
32767 - isone, isone, 16384 -isone);
}
return(0);
}
dice/read dice/read
FUNCTION
read data from a file (UNIX)
SYNTAX
#include <fcntl.h>
int r = read(fd, buf, bytes);
int fd;
void *buf;
int bytes;
DESCRIPTION
read reads data from a file starting at the current seek position.
read returns the number of bytes read or -1 if a read error occurs.
With normal files, read will always return the number of bytes
requested until the end of file is reached, in which case read may
return fewer than the number of bytes requested. If at the end of a
file, read will return 0. With devices read may or may not return the
number of bytes requested depending on the device.
|| NOTE: Refer to the file_descriptor manual page for general
|| information Unlike file pointers and file handles, the file
|| descriptor is checked for validity and will simply return an error
|| if illegal.
INPUTS
int fd; file descriptor to read from
void *buf; pointer to buffer to read data into
int len; maximum number of bytes to read
RESULTS
int r; number of bytes actually read (could be less than
len or 0), or < 0 if error.
SEE ALSO
close, creat, fcntl, fdtofh, ioctl, isatty, lseek, mkdir, open, read,
rmdir, unlink, write
EXAMPLE
#include <fcntl.h>
#include <assert.h>
main()
{
int fd;
int r;
char buf[32];
fd = open("T:xx", O_WRONLY|O_CREAT|O_TRUNC);
assert(fd >= 0);
write(fd, "FuBar\n", 6);
close(fd);
fd = open("T:xx", O_RDONLY);
assert(fd >= 0);
r = read(fd, buf, sizeof(buf)); /* sizeof(buf)==32 */
close(fd);
assert(r == 6);
/*
* note that the buffer is not terminated with
* a NULL, but since we are using write() which
* requires a length it does not matter
*/
write(1, buf, r);
}
dice/realloc dice/realloc
FUNCTION
reallocate memory allocated by calloc, malloc, or strdup (ANSI)
SYNTAX
#include <stdlib.h>
void *newptr = realloc(oldptr, bytes)
void *oldptr;
size_t bytes;
DESCRIPTION
realloc reallocates a previously allocated buffer, making it larger
or smaller. It returns a pointer to a new buffer which might be the
same as the old buffer, but might not. Data in the original buffer
is copied to the new buffer and the original buffer is freed. When
extending a buffer with realloc note that the extended bytes (beyond
the original buffer) will come up garbage. You may pass a NULL as
the first argument to realloc which basically makes realloc a malloc.
INPUTS
void *oldptr; pointer to original allocated buffer
size_t bytes; size of new buffer
RESULTS
void *newptr; pointer to new buffer
SEE ALSO
malloc, calloc, strdup
EXAMPLE
#include <string.h>
#include <assert.h>
#include <stdlib.h>
main()
{
char *s;
int len;
s = strdup("This is a test");
assert(s);
len = strlen(s);
/*
* Remember that len does not include the NULL
* byte at the end of the string
*/
s = realloc(s, len + 8); /* make more room */
assert(s);
/*
* we can use strcat since in extending the
* allocated string the NULL *was* copied along
* with the string during the realloc.
*/
strcat(s, "xx");
puts(s); /* This is a testxx */
return(0);
}
dice/rega4 dice/rega4
FUNCTION
return current contents of register A4 (DICE)
SYNTAX
char *basePtr = rega4();
DESCRIPTION
rega4 is not geta4; rega4 simply returns the current contents of the
A4 register when you need it. Note that DICE offsets the A4 register
32766 from the actual small-data base so as to be able to use the
entire -32768 to 32767 range to access 64 kilobytes of small-data.
Note that a rega4 call inside a subroutine qualified with __geta4 is
guaranteed to return the data base pointer. Also, a rega4 call from
any subroutine not called from an interrupt or a call back will
return the proper data base pointer.
## WARNING: Programs which use this function will not be able to be
## made resident.
dice/remove dice/remove
FUNCTION
delete a file (ANSI)
SYNTAX
#include <stdio.h>
int error = remove(filename);
const char *filename;
DESCRIPTION
remove deletes the specified file path returning 0 on success, a
negative number on failure. On the Amiga, an error will occur if you
try to delete a file currently opened by yourself or any other
process. remove is an ANSI function. unlink does the same thing but
is a UNIX-compatible function.
INPUTS
char *filename; filename to delete
RESULTS
int error; 0 on success, a negative number on failure
SEE ALSO
unlink
EXAMPLE
#include <stdio.h>
main()
{
int error = remove("T:XXX");
if (error < 0)
{
perror("remove(\"T:XXX\") failed");
exit(1);
}
puts("T:XXX has been deleted");
return(0);
}
dice/rename dice/rename
FUNCTION
rename a file, or move a file from one directory to another on the
same filesystem (ANSI)
SYNTAX
#include <stdio.h>
int error = rename(origname, newname);
const char *origname;
const char *newname;
DESCRIPTION
rename renames a file. You may also use rename to move a file (and
rename at the same time) to another directory on the same filesystem.
rename returns 0 on success, a negative number on failure.
INPUTS
const char *origname;
existing file const char
*newname; new filename and/or path
RESULTS
int error; 0 on success, a negative number on failure
SEE ALSO
rewind
EXAMPLE
/*
* create the file T:xxjunk and the directory
* T:junkdir then move T:xxjunk into T:junkdir
* and rename to T:yyjunk at the same time.
* As is aptly demonstrated by this example, some
* errors are not really errors. For example,
* mkdir where the dir already exists is not usually
* an error.
*/
#include <stdio.h>
#include <assert.h>
#include <errno.h>
main()
{
FILE *fp; int error;
error = mkdir("T:junkdir");
if (error < 0 && errno != EEXIST)
perror("mkdir");
fp = fopen("T:xxjunk", "w");
if (fp == NULL) {
perror("fopen"); exit(1);
}
fprintf(fp, "This was originally T:xxjunk!\n");
fclose(fp);
error = rename("T:xxjunk", "T:junkdir/yyjunk");
if (error < 0)
perror("Error renaming T:xxjunk");
else
puts("rename succeeded, look in T:junkdir");
return(0);
}
dice/rewind dice/rewind
FUNCTION
seek filepointer to beginning of file (ANSI)
SYNTAX
#include <stdio.h>
void rewind(fp);
FILE *fp;
DESCRIPTION
rewind rewinds the file to the beginning, equivalent to fseek(fp, 0L,
0);.
|| NOTE: Refer to the file_pointer manual page for general
|| information.
INPUTS
FILE *fp; file pointer to rewind
SEE ALSO
fseek, fgetpos, fsetpos
EXAMPLE
/* print a file 3 times */
#include <stdio.h>
main(int ac, char**av) {
FILE *fp;
int i;
char buf[256];
if (ac == 1) {
puts("Expected textfile argument");
exit(1);
}
fp = fopen(av[1], "r");
if (fp == NULL) {
printf("Unable to open %s\n", av[1]);
exit(1);
}
for (i = 1; i <= 3; ++i) {
rewind(fp); printf("PRINTING #%d\n", i);
while (fgets(buf, sizeof(buf), fp))
fputs(buf, stdout);
}
return(0);
}
dice/rmdir dice/rmdir
FUNCTION
delete a directory (UNIX)
SYNTAX
#include <stdio.h>
int r = rmdir(dirname);
char *dirname;
DESCRIPTION
rmdir deletes a directory. The directory must be empty for the
deletion to work. On the Amiga this call is equivalent to remove or
unlink.
INPUTS
char *dirname; name of directory to delete
RESULTS
int r; 0 if successful, non-zero if error
SEE ALSO
mkdir
EXAMPLE
#include <assert.h>
main()
{
int r;
r = mkdir("T:tmpdir");
assert(r == 0);
r = rmdir("T:tmpdir");
assert(r == 0);
}
dice/scanf,fscanf,sscanf dice/scanf,fscanf,sscanf
FUNCTION
scan formatted text and convert to variables (ANSI)
SYNTAX
#include <stdio.h>
int n = scanf(ctl, ...); /* Input: standard in */
int n = fscanf(fp, ctl, ...); /* Input: file pointer */
int n = sscanf(str,ctl, ...); /* Input: string buffer */
const char *ctl;
FILE *fp;
char *str;
DESCRIPTION
These functions scan the specified input file or buffer for fields
matching those specified by the control field. Commands starting with
% relate the scanned text to a list of pointers. The values the
pointers point to are updated (say that three times fast). Other
characters in the control field must match the scanned text exactly,
except for white space charaters, which match any length of white
space in the scanned text.
Control Field Commands
----------------------
The control field command format is as follows:
%[*][nnn][h/l/L]<conversion-specifier>
% All conversion specifiers start with %. Use %% to match a single
% in the source text.
* An optional * tells scanf to perform the conversion, but discard
the result. Do not include a destination pointer for skiped
conversions.
nnn An optional decimal number is used for string conversion to
specify a maximum field width.
h The modifier h specifies the destination should be treated as a
short integer rather, than an integer. The h conversion applies
to d, i, n, o, u, x and X.
l The modifier l specifies the destination should be treated as a
long integer, rather than an integer. The l conversion applies
to d, i, o, u, x and X.
L When used with formats e, f or g, specifies the destination
should be treated to a long double rather than a double.
Conversion Specifiers
---------------------
c With no field width specified, converts one character. With a
field width, converts the number of characters specified by the
field width into an array. The expected argument is a pointer to
a character or array of characters. No white space is skipped.
d Converts a decimal (base 10) number. The expected argument is a
pointer to an integer. The l and h modifiers may be used to
specify either a long or short integer result.
e/f/g Scans a floating point number. If the l modifier is used, a long
double pointer is expected (not implemented in DICE yet), else a
double is expected.
i Converts a number to an integer. The format should be equivalent
to that expected by strtol with a base argument of 0 (automatic
detection of format).
n This command does not scan any text. It places into an integer
the current count of processed characters.
o An octal number is expected. The value is stored to an integer.
p A pointer is expected, in the same format as the %p from printf.
The value is stored into a pointer, passed as void ** (a pointer
to any type of pointer).
s Reads a string of non-white space characters and copies into the
array specified by the argument. The argument must be of type
char * and have enough space to handle any possible string plus a
NULL terminator.
x A hexadecimal (base 16) number is expected. The value is stored
into an integer. This is equivalent to calling strtol with a
base of 16.
%% Match a single % in the input stream.
[...] Scan a scanset. Scan the input stream and place the characters
into a char * buffer until a character is read that does not
match the scanset. If a scan set begins with ^ (as in [^abcd])
then all characters are allowed except those specified in the
scanset. If a scanset begins as []abcd] or [^]abcd] then the ']'
character is included in the scan set and the set is terminated
by ']'.
|| Note: All scanf arguments are pointers. A common mistake is
|| to pass arguments directly; pointers are required. All
|| floating point arguments must be pointers to doubles.
INPUTS
char *ctl; format control string, containing % commands
FILE *fp; file pointer for fscanf
char *str; string pointer for sscanf
... pointers to variables ready to receive
conversions.
RESULTS
int n; Number of conversions that occured or -1 if no
conversions could be made (this usually means
EOF). The function may return less than the
number of requested conversions. This value does
not count any %* conversions.
SEE ALSO
sprintf, printf, fprintf, strtol
EXAMPLE
#include <stdio.h>
main(int ac, char**av)
{
int n, integer;
n = sscanf("Input: 132\n", "Input: %ld\n", &integer);
printf("First test: n=%d integer=%d ", n, integer);
short a[3] = {-1, -2, -3}; // Unscanned arguments are NOT
int b[3] = {-4, -5, -6}; // cleared - they retain
char buf1[11], buf2[11]; // former values!
buf1[0]=buf2[0]=buf2[10] = 0;
if (ac != 2) {
puts("Expected string to format!"); exit(1);
}
n = sscanf(av[1],"%hd %ho %hi %*d %X %n%10s %10c -%d-",
a+0,a+1,a+2, b+0,b+1,buf1,buf2,b+2);
printf("Second test: %d elements\n", n);
printf("a (shorts): %d %d %d\n", a[0], a[1], a[2]);
printf("b (ints) : %d %d %d\n", b[0], b[1], b[2]);
printf("buf1 : %s\nbuf2 : %s\n", buf1, buf2);
return(0);
}
/* scanf "100 100 0x100 200 0x300 reduce reuse recycle!"
** First test: n=1 integer=132 Second test: 6 elements
** a (shorts): 100 64 256
** b (ints) : 768 24 -6
** buf1 : reduce
** buf2 : reuse recy
*/
dice/setbuf,setvbuf dice/setbuf,setvbuf
FUNCTION
change a file pointer's buffering (ANSI)
SYNTAX
#include <stdio.h>
void setbuf(fp, buf);
error = setvbuf(fp, buf, mode, size);
FILE *fp; char *buf;
int mode; size_t size; int error;
DESCRIPTION
setbuf changes the internal buffer used by stdio. The buffer you
pass it must be BUFSIZ bytes in size. You can set a file pointer to
unbuffered by passing NULL for your buffer.
setvbuf supersedes this call and is, in general, a better function.
Type type argument must be one of _IOFBF (Fully Buffered), _IOLBF
(Line Buffered) or _IONBF (Non Buffered). For use with DICE it is
best to supply a buffer size, but a NULL buf pointer. DICE will
allocate buffers as they are needed.
## WARNING: If buffering is turned off for a file pointer
## representing a console device, the console device is set to
## unbuffered as well. If buffering is turned on for a file pointer
## representing a console device, the console device is set to
## buffered as well.
|| NOTE: Refer to the file_pointer manual page for general
|| information.
INPUTS
FILE *fp; file pointer to affect.
char *buf; buffer for use by the file pointer, or NULL.
int type; (setvbuf) type of buffering.
size_t size; (setvbuf) requested buffer size or zero.
int error; (setvbuf) error code (if size or type are
invalid).
EXAMPLE 1
#include <stdio.h>
main()
{
FILE *fp;
fp = fopen("CON:0/0/640/100/DICE Setbuf Test","w");
if(! fp )
exit( 10 );
fprintf(fp, "This will be buffered, ");
sleep(2);
setvbuf(fp, NULL, _IONBF, 0);
fprintf(fp, "yet these will print immediately ");
sleep(2);
fprintf(fp, "(we are unbuffered).");
sleep(4);
fprintf(fp, "\n");
setvbuf(fp, NULL, _IOLBF, 128);
fprintf(fp, "Now back to buffered... ");
sleep(2);
fprintf(fp, "(See - you had to wait).\n");
sleep(8);
fclose( fp );
return(0);
}
EXAMPLE 2
#include <stdio.h>
#define BUFFER_SIZE 128
main()
{
int c; char buf[256];
setvbuf(stdin, NULL, _IONBF, 0);
printf("Type a character: ");
fflush(stdout);
c = getchar();
printf("c = %d\n", c);
setvbuf(stdin, NULL, _IOLBF, BUFFER_SIZE);
printf("Type a line: ");
fflush(stdout);
fgets(buf, sizeof(buf), stdin);
printf("You said : %s\n", buf);
return(0);
}
dice/setjmp,longjmp dice/setjmp,longjmp
FUNCTION
setjmp: save procedure context for future long jump (ANSI)
longjmp: jump to a previously saved procedure context (ANSI)
SYNTAX
#include <setjmp.h>
int r = setjmp(enviro);
(void) longjmp(enviro, rval)
jmp_buf enviro;
int rval;
DESCRIPTION
First, setjmp stores the current procedure context into an
environment array whose type is jmp_buf. When called by a procedure
it saves the environment and returns 0. Then when called, longjmp
jumps to a previously saved environment causing execution to begin at
the setjmp call that saved that enviroment. Yet instead of returning
0 the 'resumed' setjmp returns a return value set by the longjmp
call. Jmp_buf is a typedef of an array, thus by passing a jmp_buf
structure we really pass the address of it. setjmp and longjmp are
fully compatible with dynamic stacks (-gs option to DCC).
:: Beginner's Note: setjmp and longjmp should be used sparingly, if
:: at all. They make code hard to understand, are rife with potential
:: for adding bugs and are considered even uglier than the C goto
:: statement.
In the example below main is still stacked when the longjmp occurs
and is thus valid. It would be illegal, for instance, to call a
subroutine which does a setjmp and RETURNS to you, then longjmp back
to that subroutine. The contents of the jmp_buf structure are private
and may not be modified by the program.
## WARNING: You can only longjmp to a previously saved enviroment
## that has not been unstacked. WARNING: setjmp saves the current
## state of the registers, but not any registers that get modified
## between the setjmp and the longjmp!
Thus, auto variables placed in registers (which is done so
automatically under DICE) may contain 'old' values after a longjmp if
they were modified after the setjmp. To prevent this such variables
must, by ANSI convention, be made volatile. The volatile qualifier
forces an auto variable to be placed on the stack instead of in a
register.
INPUTS
jmp_buf enviro; enviroment structure
int rval; return value (longjmp call)
RESULTS
(setjmp) int r; 0 when called directly, rval when enviroment
restored by a longjmp
SEE ALSO
onbreak, signal
EXAMPLE
#include <stdio.h>
#include <setjmp.h>
jmp_buf x;
int brk(void);
void breakme(void);
main()
{
int r;
onbreak(brk);
r = setjmp(x); // returns 0 when called by main
puts("\nArnie sez: I'll be back...");
if (r == 0)
for (;;)
breakme();
printf("Broke and jumped, r = %d\n", r);
return(0);
}
/* even though the onbreak call is supposed to return,
** we can longjmp out of it as well.
*/
int brk()
{
longjmp(x, 23);
}
void breakme()
{
puts("Break Me With ^C!");
}
dice/signal dice/signal
FUNCTION
set a signal vector for a signal (ANSI)
SYNTAX
#include <signal.h>
typedef void (*__sigfunc)(int);
__sigfunc oldfunc = signal(signo, newfunc)
int signo;
__sigfunc newfunc;
DESCRIPTION
signal sets a signal vector function for a given signal number as
defined in <signal.h> and returns the previously set function.
Currently only SIGINT causes any semi-asynchronous action to occur.
You may pass newfunc as your own signal function or one of:
SIG_ERR error (exit program)
SIG_DFL default (for break, normal operation)
SIG_IGN ignore signal (for break, ^C is now ignored)
when a signal occurs, the signal is set back to its default
condition before the handler is called. Thus, if you are
allowing multiple signals to occur you must restore the signal
vector with signal from your signal handler before it returns.
|| NOTE: On the Amiga, signals are not truly asynchronous. ^C is
|| detected during stdio calls only. No other signal is
|| implemented though you CAN modify any signal vector 0 to 31
|| and raise it with the raise call. Early versions of DICE,
|| including quite possibly this version, do not understand
|| complex type declarations containing procedural types. Thus,
|| you may have to get around the problem by building up a
|| complex procedural type with typedefs. Unlike onbreak, a
|| signal function returns no value.
INPUTS
int signo; signal to modify, usually SIGINT __sigfunc
newfunc; signal function or SIG_ERR, SIG_DFL, SIG_IGN
RESULTS
__sigfunc oldfunc;
previous signal function
SEE ALSO
raise
EXAMPLE
#include <signal.h>
void brkfunc(int);
main()
{
short i;
puts("The following is unbreakable");
sleep(1);
signal(SIGINT, SIG_IGN);
for (i = 0; i < 100; ++i) printf("1 %d\n", i);
puts("The following may be broken out of");
puts("with a cute message");
sleep(1);
signal(SIGINT, brkfunc);
for (i = 0; i < 100; ++i) printf("2 %d\n", i);
puts("The following may be broken out of");
sleep(1);
signal(SIGINT, SIG_DFL);
for (i = 0; i < 100; ++i) printf("3 %d\n", i);
puts("Hey! You never hit ^C! \
What kind of test is this!");
return(0);
}
void brkfunc(int signo)
{
printf("signo %d. Want cute? Get a kitten.\n", signo);
exit(1);
}
dice/sin,fsin dice/sin,fsin
FUNCTION
sin: return sine of a double quantity (ANSI)
fsin: return sine of a float quantity (ANSI)
LIBRARY
m.lib
SYNTAX
#include <math.h>
double a = sin(b);
double b;
float c = fsin(d);
float d;
DESCRIPTION
sin returns the sine of a double quantity; fsin returns the sine of a
floating point quantity. These functions use radian measure ("rad"
on your calulator).
INPUTS
double b; double floating point value
float d; float floating point value
RESULTS
double a; result double floating point value
float c; result float floating point value
SEE ALSO
acos, asin, atan, cos, exp, fabs, log, log10, pow, sqrt, tan, facos,
fasin
EXAMPLE
See cos for an example.
dice/sleep dice/sleep
FUNCTION
sleep for a period of time (UNIX)
SYNTAX
#include <stdio.h>
sleep(n);
int n;
DESCRIPTION
The sleep function waits for a period of time specified in seconds.
It can be interrupted by a ^C.
|| NOTE: The timekeeping of sleep is not very accurate. On the
|| Amiga, sleep is implemented with a loop of delay(50); calls.
INPUTS
int n; number of seconds to sleep
EXAMPLE
#include <stdio.h>
main(int ac, char**av)
{
puts("Sleeping for 10 seconds");
sleep(10);
puts("That was a good rest");
return(0);
}
dice/sqrt,fsqrt dice/sqrt,fsqrt
FUNCTION
sqrt: return the square root of a double (ANSI)
fsqrt: return the square root of a float (ANSI)
LIBRARY
m.lib
SYNTAX
#include <math.h>
double a = sqrt(b);
double b;
float c = fsqrt(d);
float d;
DESCRIPTION
sqrt returns the square root of a double quantity; fsqrt returns the
square root of a floating point quantity.
INPUTS
double b; double floating point value
float d; float floating point value
RESULTS
double a; double floating point value
float c; float floating point value
SEE ALSO
acos, asin, atan, cos, exp, fabs, log, log10, pow, sin, tan, facos,
fasin
EXAMPLE
/*
* compile with the math library -lm
*/
#include <math.h>
#include <stdio.h>
main()
{
{
double a = sqrt(0.25);
printf("sqrt 0.25 = %lf\n", a);
/* 0.5000 */
}
{ /* less accuracy */
float a = fsqrt(0.25);
printf("sqrt 0.25 = %lf\n", (double)a);
}
return(0);
}
dice/srand dice/srand
FUNCTION
set seed for pseudo-random number (ANSI)
SYNTAX
#include <stdio.h>
#include <stdlib.h>
(void) srand(seed)
unsigned int seed;
DESCRIPTION
srand initializes the seed for function rand.
INPUTS
unsigned int seed;
an unsigned integer used to seed the
pseudo-random
number generator via srand.
SEE ALSO
rand
EXAMPLE
See the "rand" manual page for an example
dice/stack_abort dice/stack_abort
FUNCTION
exit point when dynamic stack allocation fails (DICE)
SYNTAX
void stack_abort(void)
{
/* .. your exit code .. */
abort();
}
DESCRIPTION
When dynamic stack allocation is enabled via the -gs option and such
an allocation fails, stack_abort is called. If you do not specify a
stack_abort routine, the c.lib stack_abort function will simply call
abort.
If you do specify a stack_abort routine, you have two choices: you
can exit out of the program, or you can simply return from the
subroutine which retries the allocation and calls stack_abort again
if it fails (perhaps wait a bit in hopes memory has become
available).
The program has about 2KB of stack left at the time this function is
called. Since a low memory condition exists when this function is
called you should not do anything that might require additional
allocations!
SEE ALSO
abort, exit
dice/stat dice/stat
FUNCTION
stat a file by name (UNIX)
SYNTAX
#include <sys/stat.h>
int error = stat(name, &stat_buf);
const char *name;
struct stat stat_buf;
DESCRIPTION
stat is a UNIX-compatible call that returns information pertaining to
the file represented by its name. If 0 is returned, stat succeeded
and the fields will be filled in as follows:
st_mode Flags S_IFDIR if directory, S_IFREG if regular file, S_IREAD if
readable, S_IWRITE if writable, S_IEXEC if executable.
st_size Size of the file, in bytes.
st_blksize
Always returns 512 (for now).
st_blocks A guess at the number of actual blocks the file takes up,
including headers and side sectors.
st_ctime Time the file was last modified.
st_mtime Same as st_ctime.
st_dev Physical device ID (do not try to interpret this field, but it
does represent the DOS handler).
st_ino inode ID (usually a file block number on the Amiga).
|| NOTE: On the Amiga one normally cannot directly examine a file
|| that is exclusively locked. If this case occurs, stat will
|| attempt to scan the parent directory for the file and if that
|| doesn't work, returns -1.
INPUTS
char *name; name of file to stat
struct stat *sbuf;
address of stat structure that will be filled in
RESULTS
int error; 0 on success, < 0 on error
SEE ALSO
chdir
EXAMPLE
#include <stdio.h>
#include <fcntl.h>
#include <sys/stat.h>
main(int ac, char**av)
{
int r;
struct stat stat_buf;
if (ac == 1) {
puts("Expected a test file name");
exit(1);
}
r = stat(av[1], &stat_buf);
if (r < 0)
printf("Can't stat %s\n", av[1]);
else {
printf("File is %d bytes long\n", stat_buf.st_size);
printf("modified %s", ctime(&stat_buf.st_ctime));
}
return(0);
}
dice/stdin,stdout,stderr,EOF dice/stdin,stdout,stderr,EOF
FUNCTION
stdin: standard input channel (file pointer - MACRO)
stdout: standard output channel (file pointer - MACRO)
stderr: standard error channel (file pointer - MACRO)
EOF: special value representing End-Of-File
SYNTAX
#include <stdio.h>
DESCRIPTION
stdin is the name for the program's standard input stream, a "FILE *"
(Pointer to structure FILE). This can be redirected via command line
redirection when the program is run. stdout is a FILE * type that
represents the program's standard output stream. This can also be
redirected via command line redirection when the program is run.
stderr is a FILE * type that represents the program's standard error
stream. Currently stderr is opened by _main and represents the
console device associated with the program regardless of standard
redirections. EOF is special value, -1 in this implementation, that
represents an end of file marker. Functions that return a single
character actually return type int to allow EOF to be distinct from
valid characters. Include the file stdio.h to use these defintions.
These file pointers may be fclose'd or freopen'd at any time. The
stdio macros getchar and putchar and stdio library routines gets and
puts deal with stdin and stdout respectively while other library
routines such as perror output to stderr.
dice/stpchr dice/stpchr
FUNCTION
Search for a character in a string (UNIX)
SYNTAX
#include <string.h>
char *ptr = stpchr(s, c)
const char *s;
int c;
DESCRIPTION
This searches for the character c within the string pointed to by s.
The terminating NULL at the end of s is NOT included in the search.
A pointer to the first occurance of c in s is returned or NULL if c
could not be found. c is converted to a char by stpchr before
beginning the search.
|| NOTE: It is better to use the ANSI standard strchr and strrchr
|| functions.
INPUTS
char *s; pointer to string to search
int c; character to search for
RESULTS
char *ptr; pointer to the first occurance of the character c
in s, or NULL if c could not be found in s.
SEE ALSO
strchr, strrchr
EXAMPLE
#include <stdio.h>
#include <string.h>
#include <assert.h>
main()
{
char *s = "this is a test";
char *ptr;
ptr = stpchr(s, 'i');
assert(ptr == s + 2);
puts(ptr); /* "is is a test" */
return(0);
}
dice/stpcpy dice/stpcpy
FUNCTION
copy a string returning a pointer to the end of the destination
(UNIX)
SYNTAX
#include <string.h>
char *ptr = stpcpy(d, s);
char *d;
char *s;
DESCRIPTION
This function copies the NULL terminated string pointed to by s to
the buffer d. The NULL is copied. A pointer to the NULL character
at the end of the copied string in d is returned.
|| NOTE: stpcpy is non-standard. While a stpcpy/stpcpy combination
|| is more efficient than a strcpy/strcat combination, strcpy and
|| strcat are standard functions and thus are guaranteed to exist in
|| all environments.
INPUTS
char *d; pointer to beginning of destination buffer
char *s; pointer to beginning of source string
RESULTS
char *ptr; pointer to end of data copied to destination
buffer
SEE ALSO
strcpy, strbpl
EXAMPLE
#include <stdio.h>
#include <string.h>
main()
{
char *buf1 = "Micky ";
char *buf2 = "Moose";
char dest[32];
char *ptr;
ptr = stpcpy(dest, buf1);
stpcpy(ptr, buf2);
puts(dest); /* Micky Moose */
return(0);
}
dice/strbpl dice/strbpl
FUNCTION
unpack a string-array buffer into an array of pointers (DICE)
SYNTAX
#include <string.h>
int num = strbpl(av, max, sary)
char **av;
int max;
const char *sary;
DESCRIPTION
strbpl unpacks a string-array into an array of string pointers. The
string array is a series of NULL terminated strings strung together
and terminated by a final NULL. A pointer to each string is placed
in the arary-of-pointers (av) with a final NULL entry assuming the
number of strings does not exceed (max-1).
INPUTS
char **av; pointer to a preallocated array of pointers
int max; the maximum number of entries in the above array
char *sary; pointer to a packed string.
RESULTS
int num; number of pointers loaded into the av array not
including the final NULL. If num == max then the
av array was not large enough to fit all the
strings or the final NULL.
EXAMPLE
#include <stdio.h>
#include <string.h>
#include <assert.h>
main()
{
char *sary = "this\0is\0a\0test\0\0";
char *av[16];
int n;
#define arysize(x) (sizeof(x)/sizeof((x)[0]))
n = strbpl(av, arysize(av), sary);
assert(n == 4); /* n == 4 */
puts(av[0]); /* this */
puts(av[1]); /* is */
puts(av[2]); /* a */
puts(av[3]); /* test */
assert(av[4] == NULL); /* av[4] == NULL */
return(0);
}
dice/strcat dice/strcat
FUNCTION
concactenate a string to an existing string (ANSI)
SYNTAX
#include <string.h>
char *d = strcat(d, s);
char *d;
const char *s;
DESCRIPTION
strcat scans the destination buffer for the NULL terminator and then
appends the source string to the destination buffer (removing the
NULL terminator and placing one at the end after the concactenation).
A pointer to the beginning of the destination buffer is returned.
INPUTS
char *d; pointer to destination buffer which already
contains a string (which could be just a \0).
char *s; pointer to the NULL terminated source string
RESULTS
char *d; same as the first argument, a pointer to the
destination buffer.
SEE ALSO
strncpy, strcpy, strncat
EXAMPLE
#include <stdio.h>
#include <string.h>
main()
{
char dest[80];
char *s1 = "I had an elegant proof also, ";
char *s2 = "but the console window was too narrow...";
strcpy(dest, s1);
puts( strcat(dest, s2) ); /* returns its first arg */
}
dice/strchr dice/strchr
FUNCTION
search for a character in a string (ANSI)
SYNTAX
#include <string.h>
char *ptr = strchr(s, c)
const char *s;
int c;
DESCRIPTION
This searches for the character c within the string pointed to by s.
The terminating NULL at the end of s is included in the search. A
pointer to the first occurance of c in s is returned or NULL if c
could not be found. C is converted to a char by strchr before
beginning the search.
|| NOTE: While strchr(s, 0); may be used to find the end of the
|| string this is slow compared to using the construction: char *ptr
|| = s + strlen(s); /* ptr = end of string s */.
INPUTS
char *s; pointer to the string to search
int c; character to search for.
RESULTS
char *ptr; pointer to the first occurance of character c in
s or NULL if c could not be found in s.
SEE ALSO
strrchr
EXAMPLE
#include <stdio.h>
#include <string.h>
#include <assert.h>
main()
{
char *s = "We feel incredibly agile";
char *ptr;
ptr = strchr(s, 'i');
assert(ptr == s + 2);
puts(ptr); /* "incredibly agile" */
return(0);
}
dice/strcmp dice/strcmp
FUNCTION
compare two strings (ANSI)
SYNTAX
#include <string.h>
int r = strcmp(s1, s2);
const char *s1;
const char *s2;
DESCRIPTION
strcmp compares two strings, returning -1 if s1 < s2, 0 if s1 == s2
, and 1 if s1 > s2.
|| NOTE: strcmp converts the chars in the string to unsigned
|| quantities when comparing them. However, for portability you
|| should not strcmp strings containing negative characters (bit 7
|| set) for anything other than checking the result against 0. Use
|| the memcmp routine instead.
INPUTS
char *s1; pointer to first string
char *s2; pointer to second string
RESULTS
int r; -1, 0, or 1.
SEE ALSO
strncmp, stricmp
EXAMPLE
#include <stdio.h>
#include <string.h>
#include <assert.h>
main()
{
char *s1 = "abca";
char *s2 = "abcd";
char *s3 = "abcx";
char *s4 = "abcdx";
char *s5 = "abc";
char *x2 = "abcd";
int r;
r = strcmp(s2, x2);
/* string s2 same as string x2 */
assert(r == 0);
r = strcmp(s2, s1);
/* string s2 larger than string s1*/
assert(r > 0);
r = strcmp(s2, s3);
assert(r < 0);
r = strcmp(s2, s4);
assert(r < 0);
r = strcmp(s2, s5);
assert(r > 0);
return(0);
}
dice/strcpy dice/strcpy
FUNCTION
copy a string returning a pointer to the beginning of the destination
(ANSI)
SYNTAX
#include <string.h>
char *ptr = strcpy(d, s);
char *d;
char *s;
DESCRIPTION
strcpy copies the NULL terminated string pointed to by s to the
buffer d. The NULL is copied. The first argument is returned (a
pointer to the buffer d).
INPUTS
char *d; pointer to beginning of destination buffer
char *s; pointer to beginning of source string
RESULTS
char *ptr; same as the destination buffer pointer (d).
SEE ALSO
stpcpy
EXAMPLE
#include <stdio.h>
#include <string.h>
#include <assert.h>
/*
* Note that the stpcpy() example accomplishes the same
* thing and is more efficient, but also requires the
* use of a temporary pointer as well as cluttering the
* source and being non-standard.
* strcpy()/strcat() is more portable, though less
* efficient.
*/
main()
{
char *buf1 = "saber";
char *buf2 = "tooth";
char dest[32];
strcpy(dest, buf1);
strcat(dest, buf2);
puts(dest); /* sabertooth */
return(0);
}
dice/strcspn dice/strcspn
FUNCTION
scan a string until a character is found that matches any character
in a second string (ANSI)
SYNTAX
#include <string.h>
int len = strcspn(s, toks)
const char *s;
const char *toks;
DESCRIPTION
With strcspn, the string s is scanned until a character is found that
matches any character in the string toks. The number of characters
skipped is returned. If no character in s matches any character in
toks then the length of the string s is returned.
strcspn is normally used to search for whitespace within a string.
Note that in many cases strpbrk is more useful than strcspn.
INPUTS
char *s; pointer to string to scan
char *toks; pointer to string containing characters to
compare against
RESULTS
int len; # of characters skipped in s before a match was
found.
SEE ALSO
strpbrk, strspn
EXAMPLE
#include <stdio.h>
#include <string.h>
#include <assert.h>
main()
{
int len;
len = strcspn("hello this is a test", " \tabcd");
assert(len == 5); /* stopped at the first space */
len = strcspn("hello this is a test", " abl");
assert(len == 2); /* stopped at the first 'l' */
len = strcspn("hello", "abcd");
assert(len == 5); /* stopped at end of string 1 */
return(0);
}
dice/strdup dice/strdup
FUNCTION
duplicate a string using malloc (DICE)
SYNTAX
#include <string.h>
char *s2 = strdup(s1);
const char *s1;
DESCRIPTION
strdup allocates enough space to hold s1 including the terminating
NULL and then copies s1 into this space, returning a pointer to the
new string. NULL is returned if space could not be allocated due to
low memory conditions. Note free may be used to free the returned
string. The amount allocated is (strlen(s1) + 1).
|| NOTE: This is a non-standard function and may not exist in other C
|| environments.
INPUTS
char *s1; pointer to the string to duplicate
RESULTS
char *s2; pointer to malloc'd space containing a duplicate
of the string s1 or NULL if space could not be
malloc'd.
SEE ALSO
malloc, free, strcpy, strlen
EXAMPLE
#include <stdio.h>
#include <string.h>
#include <assert.h>
/*
* Modifying string constants (quoted strings) may
* not be entirely portable. Normally one does not
* use strdup() to accomplish the following function
* but instead declares a char array statically
* initialized with the string, such as:
* char FuBar[] = { "This is a test" };
* Which can be modified in a portable fashion without
* having to duplicate the string.
*/
main()
{
char *s1 = "this is a test";
char *s2;
s2 = strdup(s1);
s2[0] = 'x';
puts(s2); /* this is a test */
free(s2);
s2 = strdup(s1);
s2[1] = '0';
puts(s2); /* this is a test */
free(s2);
return(0);
}
dice/strerror dice/strerror
FUNCTION
return error string associated with error code (ANSI)
SYNTAX
#include <string.h>
const char *str = strerror(error); int error;
DESCRIPTION
strerror returns a read-only string associated with the specified
error, usually taken from errno after some c.lib call fails. An
unknown error will result in the string "unknown error."
INPUTS
int error; error code
RESULTS
char *str; error string
SEE ALSO
perror
EXAMPLE
#include <stdio.h>
#include <string.h>
#include <errno.h>
#include <assert.h>
main()
{
FILE *fi;
fi = fopen("ThisFileDoesNotExist", "r");
assert(fi == NULL);
puts(strerror(errno));
return(0);
}
dice/strftime dice/strftime
FUNCTION
convert broken down time into a string according to a format (ANSI)
SYNTAX
#include <time.h>
size_t len = strftime(buf, max, fmt, tm)
char *buf; size_t max;
const char *fmt;
const struct tm *tm;
DESCRIPTION
strftime formats a broken down time into a buffer according to a
format string fmt. The fmt string looks like a the format for a
printf except with different control definitions:
%% A literal '%' character.
%a The locale's abbreviated name for the day of week.
%A The locale's full name for the day of week.
%b The locale's abbr. name for the month.
%B The locale's full name for the month.
%c The locale's default representation for the date & time (ctime).
%d The day of the month 01-31.
%H The hour 00-23 (24 hour time).
%I The hour 01-12 (12 hour time).
%j The day in the year 001-366.
%m The month 01-12.
%M The minute 00-59.
%p Indication of morning or afternoon. In the US: "AM" or "PM".
%S The second 00-59.
%U The week of the year 00-53, Sunday is the first day in a week.
%w The day of the week 0-6, Sunday=0 (standard).
%W The day of the week 0-6, monday=0.
%x The locale's default representation for the date only.
%X The locale's default representation for the time only.
%y The year mod 100 (00-99).
%Y The full year (e.g. 1990).
%Z The name of the locale's time zone, nothing if unknown.
## WARNING: There must be at least max + 1 bytes in buf or you
## might unexpectedly overwrite memory.
INPUTS
char *buf; buffer to write formatted string into
size_t max; maximum size of buffer - 1
char *fmt; format string
struct tm *tm; broken down time
RESULTS
size_t len; length of formatted string in buffer or 0 if the
maximum was exceeded.
SEE ALSO
time, localtime, asctime, ctime, clock
EXAMPLE
#include <stdio.h>
#include <time.h>
main()
{
time_t t = time(NULL);
struct tm *tp = localtime(&t);
char buf[256];
strftime(buf, sizeof(buf) - 1,
"Now is %A %d %B %Y %X", tp);
puts(buf);
return(0);
}
dice/stricmp dice/stricmp
FUNCTION
compare two strings, case insensitive (UNIX)
SYNTAX
#include <string.h>
int r = stricmp(s1, s2);
const char *s1;
const char *s2;
DESCRIPTION
stricmp compares two strings, returning: -1 if s1 < s2, 0 if s1 ==
s2, or 1 if s1 > s2. differs from strcmp in that case is ignored for
alphabetic characters, i.e. a == A.
|| NOTE: NOTE= stricmp converts the chars in the string to unsigned
|| quantities when comparing them. However, for portability you
|| should not stricmp strings containing negative characters (bit 7
|| set) for anything other than checking the result against 0. Use
|| the memcmp routine instead.
INPUTS
char *s1; pointer to first string
char *s2; pointer to second string
RESULTS
int r; -1, 0, or 1.
SEE ALSO
strcmp, strncmp
EXAMPLE
#include <stdio.h>
#include <string.h>
#include <assert.h>
main()
{
char *s1 = "abCa";
char *s2 = "aBcD";
char *s3 = "aBCX";
char *s4 = "ABCdx";
char *s5 = "Abc";
char *x2 = "ABCD";
int r;
r = stricmp(s2, x2); /* string s2 same as x2 */
assert(r == 0);
r = stricmp(s2, s1); /* string s2 larger than s1 */
assert(r > 0);
r = stricmp(s2, s3);
assert(r < 0);
r = stricmp(s2, s4);
assert(r < 0);
r = stricmp(s2, s5);
assert(r > 0);
return(0);
}
dice/strins dice/strins
FUNCTION
insert one string within another (DICE)
SYNTAX
#include <string.h>
void strins(d, s);
char *d;
const char *s;
DESCRIPTION
strins inserts string s into d by shifting the string in d over
strlen(s) spaces and then copying s into the newly made hold (except
for the NULL, of course). This result is s inserted into d.
|| NOTE: There must be enough room in d to insert s; if d is an array
|| of 32 chars and contains a string of 8 chars you can insert
|| another string of, say, 10 chars, but not of 30 chars. strins is
|| not an ANSI standard function.
INPUTS
char *d; destination to insert in front of
char *s; source string to insert
SEE ALSO
strcpy, strcat, strlen
EXAMPLE
#include <stdio.h>
#include <string.h>
main()
{
char buf[32];
strcpy(buf, "This is a test");
strins(buf + 5, "<gak!> ");
puts(buf);
/* This <gak!> is a test */
return(0);
}
dice/strlen dice/strlen
FUNCTION
returns length of a string (ANSI)
SYNTAX
#include <string.h>
int len = strlen(s);
const char *s;
DESCRIPTION
When this function is used, the length of the requested string is
returned. The string is scanned until a NULL terminator is found and
the number of characters (not including the NULL) is returned.
:: Beginner's Note: The length returned by strlen does not include
:: the NULL. It is common error to forget this fact and reserve one
:: too few bytes of storage!
INPUTS
char *s; string to obtain length of
RESULTS
int len; length of string
SEE ALSO
strcpy, strcat
EXAMPLE
#include <stdio.h>
#include <string.h>
main(int ac, char **av)
{
if( ac 1 ) {
printf("%s is %d byte(s) long\n",
av[1], strlen( av[1] ) );
} else
printf("Gimme, gimme, gimme!!\n");
}
dice/strncat dice/strncat
FUNCTION
concactenate a string to an existing string up to a maximum number of
characters (ANSI)
SYNTAX
#include <string.h>
char *d = strncat(d, s, n);
char *d;
const char *s;
int n;
DESCRIPTION
strncat scans the destination buffer for the NULL terminator and then
appends the source string to the destination buffer (removing the
NULL terminator and placing one at the end after the concactenation).
However, only up to n characters is concactenated including the NULL.
If the source string is exactly n characters long no NULL will be
appended. If the source string is longer than n characters then only
the first n characters of the source string will be appended (and no
NULL will be). A pointer to the beginning of the destination buffer
is returned.
INPUTS
char *d; pointer to destination buffer which already
contains a string (which could be just a \0).
char *s; pointer to the NULL terminated source string
int n; maximum number of characters to concactenate
RESULTS
char *d; same as the first argument, a pointer to the
destination buffer.
SEE ALSO
strncpy, strcpy, strcat
EXAMPLE
#include <stdio.h>
#include <string.h>
main()
{
char d[32]; char *p;
char *s1 = "grid"; char *s2 = "lock";
strcpy( d, s1 );
p = strncat( d, s2, 10 );
puts( d ); /* gridlock */
strcpy( d,I s1 );
p = strncat( d, s2, 3 );
puts( d ); /* gridloc */
return(0);
}
dice/strncmp dice/strncmp
FUNCTION
compare two strings up to a maximum number of characters (ANSI)
SYNTAX
#include <string.h>
int r = strncmp(s1, s2, n);
const char *s1;
const char *s2;
int n;
DESCRIPTION
strncmp compares two strings, returning: -1 if s1 < s2, 0 if s1 ==
s2, or 1 if s1 > s2. strncmp works like strcmp but only up to n
characters will be compared. If all characters compare when n is
reached 0 is returned indicating that the strings matched. Fewer
characters might be compared if either string terminates (w/ a NULL)
before the maximum is reached or a compare fails (scan is stopped and
-1 or 1 is returned immediately).
|| NOTE: strncmp converts the chars in the string to unsigned
|| quantities when comparing them. However, for portability you
|| should not strncmp strings containing negative characters (bit 7
|| set) for anything other than checking the result against 0. Use
|| the memcmp routine instead.
INPUTS
char *s1; pointer to first string
char * s2; pointer to second string
int n; maximum number of characters to compare
RESULTS
int r; -1, 0, or 1.
SEE ALSO
stricmp
EXAMPLE
#include <stdio.h>
#include <string.h>
#include <assert.h>
main()
{
char *s1 = "abcaq";
char *s2 = "abcdr";
char *s3 = "abcxs";
char *s4 = "abcdxx";
char *s5 = "abc";
char *x2 = "abcdt";
int r; r = strncmp(s2, x2, 4);
assert(r == 0);
r = strncmp(s2, s1, 4);
assert(r > 0);
r = strncmp(s2, s3, 4);
assert(r < 0);
r = strncmp(s2, s4, 8);
assert(r < 0);
r = strncmp(s2, s5, 4);
assert(r > 0);
return(0);
}
dice/strncpy dice/strncpy
FUNCTION
copy a string returning a pointer to the beginning of the destination
until NULL or the specified number of characters is reached (ANSI)
SYNTAX
#include <string.h>
char *ptr = strncpy(d, s, n);
char *d;
const char *s;
int n;
DESCRIPTION
strncpy copies the NULL terminated string pointed to by s to the
buffer d. The NULL is normally copied. The first argument is
returned (a pointer to the buffer d). The copy will also be
terminated if the specified maximum is reached, in which case the
NULL is NOT copied (which makes the function useless - but hey, it
does make it standard).
INPUTS
char *d; pointer to beginning of destination buffer
char *s; pointer to beginning of source string
int len; maximum number of characters to copy
RESULTS
char *ptr; same as the destination buffer pointer (d).
SEE ALSO
stpcpy, strcpy
EXAMPLE
#include <stdio.h>
#include <string.h>
#include <assert.h>
main()
{
char *buf1 = "hello";
char *buf2 = "123";
char dest[32];
strncpy(dest, buf1, 8);
strcat(dest, buf2);
puts(dest); /* hello123 */
dest[2] = 23;
strncpy(dest, buf1, 2);
assert(dest[2] == 23); /* copy just two */
dest[2] = 0; /* we have to add the NULL */
puts(dest); /* he */
strcat(dest, buf2); /* he123 */
puts(dest);
return(0);
}
dice/strnicmp dice/strnicmp
FUNCTION
compare two strings up to a maximum number of characters, case
insensitive (UNIX)
SYNTAX
#include <string.h>
int r = strnicmp(s1, s2, n);
const char *s1;
const char *s2;
int n;
DESCRIPTION
strnicmp compares two strings, returning: -1, s1 < s2; 0, s1 ==
s2; 1, s1 > s2. strnicmp differs from strcmp in that case is
ignored for alphabetic characters (i.e., a == A) and only up to n
characters are compared. Refer to stricmp and strncmp for other
examples.
|| NOTE: strnicmp converts the chars in the string to unsigned
|| quantities when comparing them. However, for portability you
|| should not strnicmp strings containing negative characters (bit 7
|| set) for anything other than checking the result against 0. Use
|| the memcmp routine instead.
INPUTS
char *s1; pointer to first string
char *s2; pointer to second string
int n; maximum # of characters to compare
RESULTS
int r; -1, 0, or 1.
SEE ALSO
strcmp, strncmp, stricmp
EXAMPLE
#include <stdio.h>
#include <string.h>
#include <assert.h>
main()
{
char *s1 = "aBcAQ";
char *s2 = "abCDR";
char *s3 = "ABcXs";
char *s4 = "aBCDxX";
char *s5 = "aBC";
char *x2 = "AbCDt";
int r;
r = strnicmp(s2, x2, 4);
assert(r == 0);
r = strnicmp(s2, s1, 4);
assert(r > 0);
r = strnicmp(s2, s3, 4);
assert(r < 0);
r = strnicmp(s2, s4, 8);
assert(r < 0);
r = strnicmp(s2, s5, 4);
assert(r > 0);
return(0);
}
dice/strpbrk dice/strpbrk
FUNCTION
search for specific characters in a string (ANSI)
SYNTAX
#include <string.h>
char *ptr = strpbrk(s, toks)
const char *s;
char *toks;
DESCRIPTION
strpbrk searches the string s for any character in the string toks.
For example, when searching for whitespace in s, toks would contain
the space and tab character. If no character in s matches any
character in toks then NULL is returned.
INPUTS
char *s; pointer to string to scan
char *toks; pointer to string containing tokens to scan for
RESULTS
char *ptr; pointer to point in s where the character matches
any character in toks, or NULL if s was
exhausted.
SEE ALSO
strtok
EXAMPLE
#include <stdio.h>
#include <string.h>
#include <assert.h>
main()
{
char *s = "This \tis a test";
char *ptr;
ptr = strpbrk(s, " \t");
assert(ptr == s + 4);
ptr = strpbrk(ptr + 1, " \t");
assert(ptr == s + 5);
ptr = strpbrk(ptr + 1, " \t");
assert(ptr == s + 6);
ptr = strpbrk(ptr + 1, " \t");
assert(ptr == s + 9);
ptr = strpbrk(ptr + 1, "xyz"); /* doesn't find 'm */
assert(ptr == NULL);
return(0);
}
dice/strrchr dice/strrchr
FUNCTION
search for a character in a string, scan backwards (ANSI)
SYNTAX
#include <string.h>
char *ptr = strrchr(s, c)
const char *s;
int c;
DESCRIPTION
strrchr searches for the character c within the string pointed to by
s. The terminating NULL at the end of s is included in the search.
The string is searched backwards. A pointer to the last occurrance of
c in s is returned or NULL if c could not be found. C is converted
to an 8 bit quantity by strrchr.
|| NOTE: The ANSI spec does not say anything about including the NULL
|| character in the search for strrchr and some implementation may
|| thus not implement this properly.
INPUTS
char *s; pointer to the string to search
int c; character to search for
RESULTS
char *ptr; pointer to the last occurance of character c in s
or NULL if c could not be found in s.
SEE ALSO
strchr
EXAMPLE
#include <stdio.h>
#include <string.h>
#include <assert.h>
main()
{
char *s = "this is a test";
char *ptr;
ptr = strrchr(s, 'i');
assert(ptr == s + 5);
puts(ptr); /* "is a test" */
ptr = strrchr(s, 'x');
assert(ptr == NULL);
return(0);
}
dice/strspn dice/strspn
FUNCTION
scan a string until a character is found that does not match some
character in a second string (ANSI)
SYNTAX
#include <string.h>
int len = strspn(s, toks)
const char *s;
const char *toks;
DESCRIPTION
The string s is scanned until a character is found that does not
match any character in the string toks. The number of characters
skipped is returned. If every character in s matches some character
in toks then the length of the string s is returned.
strspn is normally used to skip whitespace within a string.
INPUTS
char *s; pointer to string to scan
char *toks; pointer to string containing characters to
compare against
RESULTS
int len; # of characters skipped in s before a match could
not be found
SEE ALSO
strpbrk, strcspn
EXAMPLE
#include <stdio.h>
#include <string.h>
#include <assert.h>
main()
{
int len;
len = strspn(" \t \t\t abcde test", " \t ");
assert(len == 7); /* stopped at the 'a' */
len = strspn("abcd efg", " ");
assert(len == 0); /* stopped at the 'a' */
len = strspn(" \t\t ", " \t");
assert(len == 6); /* all match, len=strlen(str); */
return(0);
}
dice/strstr dice/strstr
FUNCTION
find sub-string within another string (ANSI)
SYNTAX
#include <string.h>
char *ptr = strstr(s, sub);
const char *s;
const char *sub;
DESCRIPTION
The string s is scanned until the sub-string sub matches the string
beginning at the current scan point, and a pointer to the sub-string
within s is returned. If the sub-string could not be found NULL is
returned.
INPUTS
char *s; pointer to string to scan
char *toks; pointer to string containing characters to
compare against
RESULTS
char *ptr; point in s where sub string was found or NULL if
sub string could not be found.
SEE ALSO
strpbrk, strcspn
EXAMPLE
#include <stdio.h>
#include <string.h>
#include <assert.h>
main()
{
char *s = "abcdefghijklmnopqrstuvwxyz";
char *ptr;
ptr = strstr(s, "klm");
assert(ptr == s + 10);
puts(ptr); /* klmnopqrstuvwxyz */
return(0);
}
dice/strtod dice/strtod
FUNCTION
convert string to fp double (ANSI)
LIBRARY
m.lib
SYNTAX
#include <string.h>
double d = strtod(s, &tp);
const char *s;
char *tp;
DESCRIPTION
strtod converts a string to a floating point double. Initial
whitespace is skipped. The format of the fp number in the string is
then:
{+/-/<nothing>}ddddd[.ddddd][E{+/-/<nothing>}dddd]
Example fp strings: " +1.234E-3", "-1234", "6.5676E4", "214.2345"
INPUTS
char *s; pointer to string containing fp number
char **tp; pointer to pointer, the pointer is modified to
point to the end of the scanned fp number.
RESULTS
double d; resulting double
EXAMPLE
/*
* compile -lm to include math library
*/
#include <stdio.h>
#include <string.h>
main()
{
double d;
char *tp;
d = strtod("1.2134 3.45E2", &tp);
printf("1.2134 = %lf\n", d); /* 1.213400 */
d = strtod(tp, &tp);
printf("3.45E2 = %lf\n", d); /* 345.000000 */
return(0);
}
dice/strtok dice/strtok
FUNCTION
break up a string into arguments (ANSI)
SYNTAX
#include <string.h>
char *arg = strtok(s, toks)
char *s;
const char *toks;
DESCRIPTION
strtok breaks up a string into arguments. It determines the break
point from the toks string which contains a set of whitespace
characters (usually \t to mean space and tab). The first call to
strtok should specify the string s and toks. Initial whitespace is
skipped and the string is then scanned until the end of the first
argument is found. The string is then modified: a NULL is placed at
the end of the first argument and a pointer to the beginning of the
first argument is returned.
Further calls to strtok should pass a NULL for the string s, which
tells strtok to continue scanning the original string (whose pointer
was stored in a static char * within strtok). strtok returns
arguments until the string is exhausted, in which case it returns
NULL. The initial call to strtok can return NULL if the passed
string s contains nothing but whitespace (as specified by toks). You
can change the toks string at any time (i.e. pass a different toks
string to strtok).
## WARNING: strtok modifies the source string and returns pointers
## into it.
INPUTS
char *s; pointer to string to parse
char *toks; pointer to string containing whitespace
characters (argument delimiters)
RESULTS
char *arg; pointer into s to next argument that is NULL
terminated (s is modified).
SEE ALSO
strspn, strcspn
EXAMPLE
#include <stdio.h>
#include <string.h>
main()
{
char buf[32];
char *arg;
const char *ws = " \t";
/*
* 'This' 'is' 'a' 'test!'
*/
strcpy(buf, " This is \t \t a test!");
for (arg = strtok(buf, ws);
arg; arg = strtok(NULL, ws))
{
printf("arg = '%s'\n", arg);
}
return(0);
}
dice/strtol,strtoul dice/strtol,strtoul
FUNCTION
convert string to integer (ANSI)
SYNTAX
#include <string.h>
long v = strtol(str, &tail, base);
unsigned long v = strtoul(str, &tail, base);
const char *str;
char *tail;
int base;
DESCRIPTION
strtol converts a string into an integer using the specified base
0-36. If a non-zero base is specified conversion is done using that
base (hex numbers may still be preceeded by '0x' or '0X'). If 0 is
specified for the base then the base is determined from the first one
or two characters of the number portion of the string:
0 octal
1-9 decimal
0x hex (0x or 0X)
For bases larger than 10, alphabetic characters are used to represent
digits. Either lower case or upper case letters may be used. strtol
stores a pointer to the remainder of the string after the conversion.
strtol ignores any whitespace at the beginning of the string and also
handles an optional negative sign (which may precede the numerical
portion of the string).
If successful strtol returns the converted value as a long, 0 if it
was unable to convert anything, and an undefined result if the
converted value was out of range.
|| NOTE: strtol supersedes atoi and atol.
INPUTS
char *str; pointer to string to convert
char **tail; *tail modified to point to just after last
character converted
int base; base of conversion or 0 for autoselect
RESULTS
long v; converted result, an integer, or 0 if no
conversion could be done.
SEE ALSO
atoi, atol, strtod
EXAMPLE
#include <stdio.h>
#include <string.h>
main(int ac, char**av)
{
long v;
char *tail;
if (ac != 3)
{
puts("testprg <string> <base>");
puts("testprg 0123abc 0");
puts("testprg 0x1000 0");
puts("testprg 0123abc 16");
exit(1);
}
v = strtol(av[1], &tail, atoi(av[2]));
printf("v = %d, tail = %s\n", v, tail);
return(0);
}
dice/system dice/system
FUNCTION
call system shell with a command line (ANSI)
SYNTAX
#include <stdio.h>
#include <stdlib.h>
int r = system(buf);
const char *buf;
DESCRIPTION
system calls the system shell with the specified command line,
returning the exit code of the command or -1 if it was unable to run
the command.
|| NOTE: FOR PROGRAMS COMPILED UNDER 1.3, even if run in 2.0
|| enviroment, the system call will not return the exit code from the
|| command, but return -1 if could not be run, 0 if it could.
|| NOTE: FOR PROGRAMS COMPILED UNDER 2.0, system will use the 2.0
|| calls and return a proper exit code when running under 2.0, and
|| will use execute if running under 1.3.
INPUTS
char *buf; command line to run, like a normal AmigaDOS CLI
command line.
RESULTS
int r; return code
EXAMPLE
main()
{
int r;
r = system("c:type s:startup-sequence");
printf("System returns %d\n", r);
}
dice/tan,ftan dice/tan,ftan
FUNCTION
tan: return tan of a double quantity (ANSI)
ftan: return tan of a float quantity (ANSI)
LIBRARY
m.lib
SYNTAX
#include <math.h>
double a = tan(b); double b;
float c = ftan(d); float d;
DESCRIPTION
tan returns the tangent of a double quantity; ftan returns the
tangent of a floating point quantity.
INPUTS
double b; double floating point value
float d; float floating point value
RESULTS
double a; double floating point value
float c; float floating point value
SEE ALSO
acos, asin, atan, cos, exp, fabs, log, log10, pow, sin, sqrt, tan,
facos, fasin
EXAMPLE
/*
* compile with the math library -lm
*/
#include <math.h>
#include <stdio.h>
main()
{
{
double a = tan(0.25);
printf("tan 0.25 = %lf\n", a); /* 0.2553 */
}
{ /* less accuracy */
float a = ftan(0.25);
printf("tan 0.25 = %lf\n", (double)a);
}
return(0);
}
dice/time dice/time
FUNCTION
get current time (ANSI)
SYNTAX
#include <time.h>
time_t t = time(NULL);
or
time(&t);
time_t t;
DESCRIPTION
time returns the current time as a time_t and also copies it into a
time_t if the address of said is passed as an argument. You may pass
NULL as an argument in which case the time is only returned.
The time is returned as seconds since some base date, time_t is
normally an unsigned long.
INPUTS
time_t *t; pointer to a time_t or NULL
RESULTS
time_t t; a time_t
SEE ALSO
time, localtime, asctime, strftime, ctime, clock
EXAMPLE
#include <stdio.h>
#include <time.h>
main()
{
time_t t = time(NULL);
printf("t = %u\n", t);
return(0);
}
dice/tmpfile dice/tmpfile
FUNCTION
create a temporary file (ANSI)
SYNTAX
#include <stdio.h>
FILE *fp = tmpfile(void);
DESCRIPTION
tmpfile creates a temporary file and returns a file pointer. The
name of the file is not accessible. The file pointer is available or
reading, writing, and seeking (as in rewind, fseek). The file is
initially empty. This call may be used to create a temporary file
that will automatically be removed when you fclose it. tmpfile
returns a FILE pointer or NULL if it was unable to create the file.
INPUTS
none
RESULTS
FILE *fp; opened temporary file
SEE ALSO
tmpnam, fopen, fclose
EXAMPLE
#include <stdio.h>
#include <assert.h>
main()
{
FILE *fp = tmpfile();
char buf[256];
assert(fp);
fputs("This is a test of\n"
"a temporary file\n"
"fubar bletch\n", fp);
rewind(fp);
while (fgets(buf, sizeof(buf), fp))
{
fputs(buf, stdout);
}
fclose(fp); /* close and delete the file */
return(0);
}
dice/tmpnam dice/tmpnam
FUNCTION
create a unique, temporary file name (ANSI)
SYNTAX
#include <stdio.h>
char *filename = tmpnam(buf);
char *buf;
DESCRIPTION
tmpnam creates a unique temporary file name meant never to be seen by
the user. The filename tmpnam creates will be no more than L_tmpnam
bytes long (L_tmpnam is a macro in <stdio.h>), including the NULL so
you can simply declare a buffer: char buf[L_tmpnam];.
tmpnam returns the buffer into which it created the temporary file
name. If you specify a non-NULL buffer it returns its first
argument. If you pass NULL to tmpnam then tmpnam will use its down
internal static buffer (overwritting any previous name that was
stored in said buffer) and return a pointer to that.
INPUTS
char *buf; optional buffer of at least L_tmpnam bytes to
hold the temporary file name or NULL to have
tmpnam() use its own internal buffer.
RESULTS
char *ptr; pointer to buffer (buf if buf != NULL)
SEE ALSO
tmpfile
EXAMPLE
#include <stdio.h>
#include <assert.h>
main()
{
char buf[L_tmpnam]; char *ptr;
ptr = tmpnam(NULL); puts(ptr);
assert(tmpnam(buf) == buf);
/* returns argument */
puts(buf); /* haven't overwritten it yet */
printf("%s (same as first)\n", ptr);
assert(tmpnam(NULL) == ptr);
/* that will overwrite it! */
puts(ptr);
return(0);
}
dice/tolower,toupper dice/tolower,toupper
FUNCTION
convert a character into lower or upper case (ANSI)
SYNTAX
#include <ctype.h>
int lc = tolower(c);
int uc = toupper(c);
int c;
|| NOTE: These are MACROS if you #include <ctype.h>, subroutine calls
|| if you do not.
DESCRIPTION
toupper converts a character from lower to upper case, while tolower
does the reverse. Characters that are not of type upper or lower
case (see isupper and islower) are left unchanged.
|| NOTE: Characters in the -1 to 255 range are valid inputs.
|| Characters less than -1 or larger than 255 are illegal and the
|| results will be random. If you are passing a CHAR, you must cast
|| it to an UNSIGNED CHAR first. EOF is a valid input an always
|| returns false (zero).
INPUTS
int c; character to be converted
RESULTS
int lc, uc; converted character
SEE ALSO
isalnum, isalpha, iscntrl, isdigit, isgraph, islower, isprint,
ispunct, isspace, isupper, isxdigit
EXAMPLE
#include <stdio.h>
#include <ctype.h>
main()
{
int c;
/* Print all 256 characters, showing conversions */
for( c=0; c<256; c++) {
if( (c & 31) == 0 ) /* 32 per line */
printf("\n%02x: ", c);
if( isprint( c ) ) /* if printable ... */
printf("%c", tolower( c ) );
else
printf("%c", 127); /* if not-printable */
}
printf("\n");
return( 0 );
}
dice/ungetc dice/ungetc
FUNCTION
push a character back onto a file pointer's input stream (ANSI)
SYNTAX
#include <stdio.h>
int r = ungetc(c, fp);
int c;
FILE *fp;
DESCRIPTION
ungetc pushes the specified character back onto the input stream, as
if it had not been read. Only ONE character may be pushed back onto
an input stream at a time. If all went well, the return value r is
equal to c. Else EOF is returned if too many characters were pushed
back. Some implementations of C allow multiple characters to be
pushed back. The majority, including DICE, allows only one.
ungetc is useful when, in scanning an input stream, you overshoot the
'last' character you wanted a particular routine to retrieve. This
routine can push the character back onto the input stream with ungetc
so another routine's getc (getchar, fread, fgetc, etc...) will get
that character back.
INPUTS
int c; character to push back onto input stream
FILE *fp; file pointer stream to push character on to.
RESULTS
int r; pushed character (c) if no error, EOF if error
SEE ALSO
getc, getchar, fread, fgetc
EXAMPLE
#include <stdio.h>
#include <ctype.h>
main()
{
void scan_number();
void scan_alpha();
puts("Enter nnnaaannn where n=digit a=alpha");
puts("Example: 1234abcd99");
printf("? ");
fflush(stdout);
scan_number(); puts("--");
scan_alpha(); puts("--");
scan_number(); return(0);
}
static void scan_number()
{
short c;
for (c = getchar(); c >= '0' && c <= '9';
c = getchar())
{
printf("digit: %c\n", c);
}
if (c != EOF)
ungetc(c, stdin);
}
static void scan_alpha()
{
short c;
for (c = getchar();
tolower(c) >= 'a' && tolower(c) <= 'z';
c =getchar())
{
printf("alpha: %c\n", c);
}
if (c != EOF) ungetc(c, stdin);
}
dice/unlink dice/unlink
FUNCTION
delete a file (UNIX)
SYNTAX
#include <stdio.h>
int r = unlink(filename);
char *filename;
DESCRIPTION
unlink deletes a file, equivalent to remove. This call deletes a file
from the filesystem. unlink exists for UNIX compatibility only. Use
rmdir to delete a directory if you wish to maintain portability.
INPUTS
char *filename; name of file to delete
RESULTS
int r; 0 if successful, non-zero if error
SEE ALSO
close, creat, fcntl, fdtofh, ioctl, isatty, lseek, mkdir, open, read,
rmdir, unlink, write
EXAMPLE
main()
{
int r;
r = unlink("T:xx");
if (r == 0)
puts("Deleted T:xx");
else
puts("Unable to delete t:xx or it does not exist");
return(0);
}
dice/wbmain dice/wbmain
FUNCTION
main program entry when run from Workbench (DICE)
SYNTAX
#include <startup.h>
int wbmain(struct WBStartup *wbs)
{
/* your main code goes here */
return(exitcode);
}
DESCRIPTION
The wbmain routine is the entry point called after normal
initialization of c.lib and the program enviroment is done by the
startup module (c.o) and _main() routine (in c.lib). wbmain is called
when the program is run from the workbench, main is called when the
program is run from the CLI. The exit code is ignored. The standard
workbench startup message is passed to wbmain, you can process or
ignore this message as you like but should NOT ReplyMsg it. We
repeat, do not ReplyMsg it. When you return from wbmain or exit out
of the program the exit code will automatically deal with the
message.
SEE ALSO
main
EXAMPLE
/*
* If run from the workbench this program will create a
* file T:XX instead of printing something on the
* console (since there is no console in that case).
*/
#include <stdio.h>
int main(int ac, char**av)
{
puts("This was run from a CLI");
return(0);
}
int wbmain(msg)
void *msg; /* cheat to make the example less complex */
{
FILE *fi = fopen("T:xx", "w");
fprintf(fi, "This was run from the WORKBENCH\n");
fclose(fi);
}
dice/write dice/write
FUNCTION
write data to a file (UNIX)
SYNTAX
#include <fcntl.h>
int r = write(fd, buf, bytes);
int fd;
void *buf;
int bytes;
DESCRIPTION
write writes data to a file, starting at the current seek position.
It extends the file if necessary, or else writes over existing data.
With normal files, write will always return the number of bytes
requested and fewer only if an error occurs. With devices write may
or may not return the number of bytes requested depending on the
device, though usually it does.
|| NOTE: Refer to the file_descriptor manual page for general
|| information. Unlike file pointers and file handles, the file
|| descriptor is checked for validity and will simply return an error
|| if illegal.
INPUTS
int fd; file descriptor to write to void
*buf; pointer to buffer to write data from
int len; number of bytes to write
RESULTS
int r; number of bytes actually written, usually an
error if r !=len.
SEE ALSO
close, creat, fcntl, fdtofh, ioctl, isatty, lseek, mkdir, open, read,
rmdir, unlink
EXAMPLE
See open for an example
dice/x.o dice/x.o
FUNCTION
autoinit terminating tags (DICE)
LIBRARY
x.o
DESCRIPTION
The X.O module is the normally the last object module specified when
linking. DICE has a very unique and elegant system of creating
automatic initialization and exit code. The X.O module terminates
these special sections.
Autoinit/exit sections work as follows: any object module may define
a specially named section which will be linked, in sequence, with
other module's sections of the same name. These sections contain
only code and no RTS. The terminating module X.O adds a single RTS
to each section, allowing the base of the section to be called by the
startup/exit module (C.O). Execution propigates through all
autoinit/exit routines before hitting the RTS placed in the section
by X.O. DICE uses autoinit/exit sections to handle the following
things:
1) Code to initialize initialized data containing references to other
initialized data (i.e. int a, *b = &a;) when the code must be
made residentable. This precludes the need for the startup code
to handle Data-Data 32-bit relocations for resident code.
2) Code to open libraries whos base variables are referenced but
never declared. _DOSBase and the various floating point libraries
are automatically opened in this way whenever library calls to
them are made. This precludes the need for DICE to have massive,
complex, and many times unncessary code in c.lib to handle these
situations.
3) Code to close libraries that were openned by (2) on exit.
4) Entry points for the special __autoinit keyword.
SEE ALSO
c.o
EXAMPLE
dlink dlib:c.o myprog.o dlib:x.o -o myprog -v
